diff --git a/doc/changelog.d/4154.miscellaneous.md b/doc/changelog.d/4154.miscellaneous.md new file mode 100644 index 00000000000..b43ce569fa8 --- /dev/null +++ b/doc/changelog.d/4154.miscellaneous.md @@ -0,0 +1 @@ +Feat: ``solu`` - part 1 \ No newline at end of file diff --git a/doc/source/mapdl_commands/solution/2d_to_3d_analysis.rst b/doc/source/mapdl_commands/solution/2d_to_3d_analysis.rst deleted file mode 100644 index 6c9dab12259..00000000000 --- a/doc/source/mapdl_commands/solution/2d_to_3d_analysis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _ref_2d_to_3d_analysis_commands_api: - -***************** -2D to 3D analysis -***************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands apply to 2-D to 3-D analyses. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.map2dto3d diff --git a/doc/source/mapdl_commands/solution/_gap_conditions.rst b/doc/source/mapdl_commands/solution/_gap_conditions.rst new file mode 100644 index 00000000000..296a77543ec --- /dev/null +++ b/doc/source/mapdl_commands/solution/_gap_conditions.rst @@ -0,0 +1,20 @@ + +.. _ref__gap_conditions: + + +GapConditions +============= + + +.. currentmodule:: ansys.mapdl.core._commands.solution._gap_conditions + +.. autoclass:: ansys.mapdl.core._commands.solution._gap_conditions.GapConditions + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + GapConditions.gp + GapConditions.gpdele + GapConditions.gplist diff --git a/doc/source/mapdl_commands/solution/_nonlinear_options.rst b/doc/source/mapdl_commands/solution/_nonlinear_options.rst new file mode 100644 index 00000000000..6e76a935de7 --- /dev/null +++ b/doc/source/mapdl_commands/solution/_nonlinear_options.rst @@ -0,0 +1,18 @@ + +.. _ref__nonlinear_options: + + +NonlinearOptions +================ + + +.. currentmodule:: ansys.mapdl.core._commands.solution._nonlinear_options + +.. autoclass:: ansys.mapdl.core._commands.solution._nonlinear_options.NonlinearOptions + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + NonlinearOptions.crplim diff --git a/doc/source/mapdl_commands/solution/_status.rst b/doc/source/mapdl_commands/solution/_status.rst new file mode 100644 index 00000000000..35de48f565d --- /dev/null +++ b/doc/source/mapdl_commands/solution/_status.rst @@ -0,0 +1,18 @@ + +.. _ref__status: + + +Status +====== + + +.. currentmodule:: ansys.mapdl.core._commands.solution._status + +.. autoclass:: ansys.mapdl.core._commands.solution._status.Status + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + Status.gap diff --git a/doc/source/mapdl_commands/solution/additive_manufacturing.rst b/doc/source/mapdl_commands/solution/additive_manufacturing.rst new file mode 100644 index 00000000000..cca92d593e9 --- /dev/null +++ b/doc/source/mapdl_commands/solution/additive_manufacturing.rst @@ -0,0 +1,26 @@ + +.. _ref_additive_manufacturing: + + +AdditiveManufacturing +===================== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.additive_manufacturing + +.. autoclass:: ansys.mapdl.core._commands.solution.additive_manufacturing.AdditiveManufacturing + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + AdditiveManufacturing.ambeam + AdditiveManufacturing.ambuild + AdditiveManufacturing.amenv + AdditiveManufacturing.ammat + AdditiveManufacturing.ampowder + AdditiveManufacturing.amresult + AdditiveManufacturing.amstep + AdditiveManufacturing.amsupports + AdditiveManufacturing.amtype diff --git a/doc/source/mapdl_commands/solution/analysis_2d_to_3d.rst b/doc/source/mapdl_commands/solution/analysis_2d_to_3d.rst new file mode 100644 index 00000000000..bf05af74d64 --- /dev/null +++ b/doc/source/mapdl_commands/solution/analysis_2d_to_3d.rst @@ -0,0 +1,18 @@ + +.. _ref_analysis_2d_to_3d: + + +Analysis2DTo3D +============== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.analysis_2d_to_3d + +.. autoclass:: ansys.mapdl.core._commands.solution.analysis_2d_to_3d.Analysis2DTo3D + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + Analysis2DTo3D.map2dto3d diff --git a/doc/source/mapdl_commands/solution/analysis_options.rst b/doc/source/mapdl_commands/solution/analysis_options.rst index 238dc71294c..3c0ae38913f 100644 --- a/doc/source/mapdl_commands/solution/analysis_options.rst +++ b/doc/source/mapdl_commands/solution/analysis_options.rst @@ -1,64 +1,69 @@ -.. _ref_analysis_options_commands_api: -**************** -Analysis options -**************** +.. _ref_analysis_options: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to set general analysis options. +AnalysisOptions +=============== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.analysis_options + +.. autoclass:: ansys.mapdl.core._commands.solution.analysis_options.AnalysisOptions .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.abextract - Mapdl.accoption - Mapdl.adams - Mapdl.antype - Mapdl.ascres - Mapdl.asol - Mapdl.bcsoption - Mapdl.cgrow - Mapdl.cmatrix - Mapdl.cmsopt - Mapdl.cncheck - Mapdl.cnkmod - Mapdl.cntr - Mapdl.cutcontrol - Mapdl.ddoption - Mapdl.dmpext - Mapdl.dmpoption - Mapdl.dspoption - Mapdl.exbopt - Mapdl.ematwrite - Mapdl.eqslv - Mapdl.eresx - Mapdl.escheck - Mapdl.essolv - Mapdl.expass - Mapdl.gauge - Mapdl.gmatrix - Mapdl.lanboption - Mapdl.lumpm - Mapdl.moddir - Mapdl.monitor - Mapdl.msave - Mapdl.msolve - Mapdl.opncontrol - Mapdl.outaero - Mapdl.ovcheck - Mapdl.pcgopt - Mapdl.perturb - Mapdl.prscontrol - Mapdl.pscontrol - Mapdl.rate - Mapdl.resvec - Mapdl.rstoff - Mapdl.scopt - Mapdl.seexp - Mapdl.seopt - Mapdl.snoption - Mapdl.solve - Mapdl.stabilize - Mapdl.thexpand - Mapdl.thopt + AnalysisOptions.abextract + AnalysisOptions.accoption + AnalysisOptions.adams + AnalysisOptions.antype + AnalysisOptions.ascres + AnalysisOptions.asol + AnalysisOptions.bcsoption + AnalysisOptions.cjump + AnalysisOptions.cload + AnalysisOptions.cmatrix + AnalysisOptions.cmsopt + AnalysisOptions.cnkmod + AnalysisOptions.cntr + AnalysisOptions.cutcontrol + AnalysisOptions.ddoption + AnalysisOptions.dmpext + AnalysisOptions.dmpoption + AnalysisOptions.dspoption + AnalysisOptions.ematwrite + AnalysisOptions.eqslv + AnalysisOptions.eresx + AnalysisOptions.exbopt + AnalysisOptions.expass + AnalysisOptions.gauge + AnalysisOptions.gmatrix + AnalysisOptions.invopt + AnalysisOptions.lanboption + AnalysisOptions.lumpm + AnalysisOptions.moddir + AnalysisOptions.monitor + AnalysisOptions.msave + AnalysisOptions.msolve + AnalysisOptions.opncontrol + AnalysisOptions.outaero + AnalysisOptions.pcgopt + AnalysisOptions.perturb + AnalysisOptions.pivcheck + AnalysisOptions.prscontrol + AnalysisOptions.pscontrol + AnalysisOptions.psolve + AnalysisOptions.rate + AnalysisOptions.resvec + AnalysisOptions.rstoff + AnalysisOptions.scopt + AnalysisOptions.seexp + AnalysisOptions.seopt + AnalysisOptions.snoption + AnalysisOptions.solve + AnalysisOptions.stabilize + AnalysisOptions.thexpand + AnalysisOptions.thopt + AnalysisOptions.toffst diff --git a/doc/source/mapdl_commands/solution/birth_and_death.rst b/doc/source/mapdl_commands/solution/birth_and_death.rst index 9bd5fec5e2c..5f25d02fbb9 100644 --- a/doc/source/mapdl_commands/solution/birth_and_death.rst +++ b/doc/source/mapdl_commands/solution/birth_and_death.rst @@ -1,16 +1,20 @@ -.. _ref_birth_and_death_commands_api: -*************** -Birth and death -*************** +.. _ref_birth_and_death: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used for the birth and death option for elements. +BirthAndDeath +============= + + +.. currentmodule:: ansys.mapdl.core._commands.solution.birth_and_death + +.. autoclass:: ansys.mapdl.core._commands.solution.birth_and_death.BirthAndDeath .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.ealive - Mapdl.ekill - Mapdl.estif + BirthAndDeath.ealive + BirthAndDeath.ekill + BirthAndDeath.estif diff --git a/doc/source/mapdl_commands/solution/dynamic_options.rst b/doc/source/mapdl_commands/solution/dynamic_options.rst index 9b1a3d690d7..c94a5f6b74a 100644 --- a/doc/source/mapdl_commands/solution/dynamic_options.rst +++ b/doc/source/mapdl_commands/solution/dynamic_options.rst @@ -1,38 +1,45 @@ -.. _ref_dynamic_options_commands_api: -*************** -Dynamic options -*************** +.. _ref_dynamic_options: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define options for dynamic analyses. +DynamicOptions +============== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.dynamic_options + +.. autoclass:: ansys.mapdl.core._commands.solution.dynamic_options.DynamicOptions .. autosummary:: - :toctree: _autosummary/ - - Mapdl.alphad - Mapdl.betad - Mapdl.dmprat - Mapdl.dmpstr - Mapdl.frqscl - Mapdl.harfrq - Mapdl.hrexp - Mapdl.hrocean - Mapdl.hropt - Mapdl.hrout - Mapdl.lvscale - Mapdl.mascale - Mapdl.mdamp - Mapdl.mdplot - Mapdl.midtol - Mapdl.modcont - Mapdl.modseloption - Mapdl.modopt - Mapdl.mxpand - Mapdl.qrdopt - Mapdl.rigid - Mapdl.subopt - Mapdl.timint - Mapdl.tintp - Mapdl.trnopt + :template: base.rst + :toctree: _autosummary + + + DynamicOptions.alphad + DynamicOptions.betad + DynamicOptions.dampopt + DynamicOptions.dmprat + DynamicOptions.dmpstr + DynamicOptions.frqscl + DynamicOptions.harfrq + DynamicOptions.hrexp + DynamicOptions.hrocean + DynamicOptions.hropt + DynamicOptions.hrout + DynamicOptions.kryopt + DynamicOptions.lvscale + DynamicOptions.mascale + DynamicOptions.mcfopt + DynamicOptions.mdamp + DynamicOptions.mdplot + DynamicOptions.midtol + DynamicOptions.modcont + DynamicOptions.modopt + DynamicOptions.modseloption + DynamicOptions.mxpand + DynamicOptions.qrdopt + DynamicOptions.rigid + DynamicOptions.subopt + DynamicOptions.timint + DynamicOptions.tintp + DynamicOptions.trnopt diff --git a/doc/source/mapdl_commands/solution/index.rst b/doc/source/mapdl_commands/solution/index.rst new file mode 100644 index 00000000000..105a02abf3e --- /dev/null +++ b/doc/source/mapdl_commands/solution/index.rst @@ -0,0 +1,30 @@ + +.. _ref_solution: + +Solution +======== + +.. list-table:: + + * - :ref:`ref_analysis_options` + * - :ref:`ref_dynamic_options` + * - :ref:`ref_additive_manufacturing` + * - :ref:`ref__nonlinear_options` + * - :ref:`ref_birth_and_death` + * - :ref:`ref__status` + * - :ref:`ref__gap_conditions` + * - :ref:`ref_analysis_2d_to_3d` + + +.. toctree:: + :maxdepth: 1 + :hidden: + + analysis_options + dynamic_options + additive_manufacturing + _nonlinear_options + birth_and_death + _status + _gap_conditions + analysis_2d_to_3d diff --git a/src/ansys/mapdl/core/_commands/solution/__init__.py b/src/ansys/mapdl/core/_commands/solution/__init__.py index 38fa021bedd..50193b80dfc 100644 --- a/src/ansys/mapdl/core/_commands/solution/__init__.py +++ b/src/ansys/mapdl/core/_commands/solution/__init__.py @@ -21,7 +21,11 @@ # SOFTWARE. from . import ( - all_others, + _gap_conditions, + _nonlinear_options, + _status, + additive_manufacturing, + analysis_2d_to_3d, analysis_options, birth_and_death, dynamic_options, diff --git a/src/ansys/mapdl/core/_commands/solution/_gap_conditions.py b/src/ansys/mapdl/core/_commands/solution/_gap_conditions.py new file mode 100644 index 00000000000..3ec7385a57e --- /dev/null +++ b/src/ansys/mapdl/core/_commands/solution/_gap_conditions.py @@ -0,0 +1,234 @@ +# 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 GapConditions: + + def gp( + self, + node1: str = "", + node2: str = "", + lab: str = "", + stif: str = "", + gap: str = "", + damp: str = "", + **kwargs, + ): + r"""Defines a gap condition for transient analyses. + + Mechanical APDL Command: `GP `_ + + Parameters + ---------- + node1 : str + Node I of gap. If ``NODE1`` = P, graphical picking is enabled and all remaining command fields + are ignored (valid only in the GUI). + + node2 : str + Node J of gap (must be different from ``NODE1`` ). Non-grounded gap nodes must be defined as + master degrees of freedom or be unconstrained, active DOF in a full analysis type. Grounded gap + nodes (those not defined as MDOF) need not appear elsewhere in the model. + + lab : str + Direction of gap action in the nodal coordinate system (implied from the following force + labels): FX, FY, FZ, MX, MY, MZ. + + stif : str + Stiffness (Force/Length) of closed gap (may be positive or negative). + + High stiffness requires a small integration time step for numerical stability. + + gap : str + Initial size of gap. A zero (or positive) value assumes an initially open gap. A negative value + defines an interference condition. For a rotational gap, ``GAP`` should be in radians. + + damp : str + Damping coefficient (Force\2Time/Length) of closed gap using pseudo velocity (Newmark finite + difference expansion scheme). + + Notes + ----- + + .. _GP_notes: + + Defines a gap condition for the mode superposition transient analysis ( :ref:`antype`,TRANS with + :ref:`trnopt`,MSUP). If used in SOLUTION, this command is valid only within the first load step. Gap + conditions specified in subsequent load steps are ignored. + + Repeat :ref:`gp` command for additional gap conditions. Gaps are numbered sequentially as input. + + Gaps may be renumbered by the program during the solution (see output listing) + + The mode-superposition transient analysis does not allow gap action with the standard gap elements. + However, you can define gap conditions which are similar to gap elements; gap conditions can be + specified between surfaces that are expected to contact (impact) each other during the transient. + The gap condition simulates the basic gap action of the ``COMBIN40`` element. + + The gap condition is treated as an explicit force (equal to the interference times contact + stiffness) and affects only the load vector calculation and not the stiffness matrix. The + interference is calculated from the displacement extrapolated from the previous time points. + + Gap conditions can only be defined between two master degree of freedom (DOF) nodes or between + master DOF nodes and ground, as shown in the following figure. + + .. figure::../../../images/_commands/GSTR5-2.svg + + Master degrees of freedom are the unconstrained and active degrees of freedom. Gap nodes not defined + as active degrees of freedom or attached to an element are assumed to be grounded. Grounded gap + nodes do not need a spatial location, nor do they need to be located on an element. + + Gap conditions may be defined in parallel (across the same nodes), with varying gap and stiffness + values, to simulate a nonlinear (piecewise) force-deflection curve. + + The gap direction is determined from the force label input on the :ref:`gp` command; that is, FX + defines a translational gap acting in the UX nodal degree of freedom direction, and MZ defines a + rotational gap acting in the nodal ROTZ degree of freedom direction. The actual degree of freedom + directions available for a particular node depends upon the degrees of freedom associated with the + element types ( :ref:`et` ) at that node. + + If the coordinate systems of the nodes connecting the gap are rotated relative to each other, the + same degree of freedom may be in different directions. The gap, however, assumes only a one- + dimensional action. Nodes I and J may be anywhere in space (preferably coincident). No moment + effects are included due to noncoincident nodes. That is, if the nodes are offset from the line of + action, moment equilibrium may not be satisfied. + + The contact stiffness value represents the stiffness of the closed gap. Stiffness values are related + to the integration time step size and should be physically reasonable. High stiffness will require a + small integration time step; otherwise, due to the displacement extrapolation, the solution may go + unstable. Negative stiffness values may be used with gaps in parallel to produce a decreasing force- + deflection curve. + + The order of specifying the gap nodes is important; that is, a gap condition connecting two nodes + will act differently depending upon which node is specified first on the :ref:`gp` command. For + example, for Node 1 at ``X`` = 0.0, Node 2 at _nolinebreak ? ``X`` = + 0.1 /_nolinebreak ?, and the gap defined from Node 1 to 2, a displacement of Node 1 greater than + Node 2 will cause the gap to close. For the gap defined from Node 2 to 1, a displacement of Node 2 + greater than Node 1 will cause the gap to close (like a hook action). In general, the gap closes + whenever the separation (defined as U:sub:`J` - U:sub:`I` + ``GAP`` ) + is negative. U:sub:`J` is the displacement of node J, U:sub:`I` is the displacement of node I, and + ``GAP`` is the input gap value. The gap force output appears in the printout only for the time steps + for which the gap is closed. A negative spring force is always associated with a closed gap (even + with the hook option). + + Some guidelines to define gap conditions are presented below: + + * Use enough gap conditions to obtain a smooth contact stress distribution between the contacting + surfaces. + + * Define a reasonable gap stiffness. If the stiffness is too low, the contacting surfaces may + overlap too much. If the stiffness is too high, a very small time step will be required during + impact. A general recommendation is to specify a gap stiffness that is one or two orders of + magnitude higher than the adjacent element stiffness. You can estimate the adjacent element + stiffness using AE/L, where A is the contributing area around the gap condition, E is the elastic + modulus of the softer material at the interface, and L is the depth of the first layer of elements + at the interface. + + * A mode-superposition transient using the nonlinear gap damping provided through the ``DAMP`` field + runs faster than a full transient analysis using a gap element ( ``COMBIN40`` ). + + Use the :ref:`gplist` command to list gap conditions and the :ref:`gpdele` command to delete gap + conditions. + + This command is also valid in PREP7. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = f"GP,{node1},{node2},{lab},{stif},{gap},{damp}" + return self.run(command, **kwargs) + + def gpdele(self, gap1: str = "", gap2: str = "", ginc: str = "", **kwargs): + r"""Deletes gap conditions. + + Mechanical APDL Command: `GPDELE `_ + + Parameters + ---------- + gap1 : str + Delete gap conditions from ``GAP1`` to ``GAP2`` (defaults to ``GAP1`` ) in steps of ``GINC`` + (defaults to 1). + + gap2 : str + Delete gap conditions from ``GAP1`` to ``GAP2`` (defaults to ``GAP1`` ) in steps of ``GINC`` + (defaults to 1). + + ginc : str + Delete gap conditions from ``GAP1`` to ``GAP2`` (defaults to ``GAP1`` ) in steps of ``GINC`` + (defaults to 1). + + Notes + ----- + + .. _GPDELE_notes: + + Deletes gap conditions defined with the :ref:`gp` command. Gap conditions following those deleted + are automatically compressed and renumbered. If used in SOLUTION, this command is valid only within + the first load step. + + This command is also valid in PREP7. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = f"GPDELE,{gap1},{gap2},{ginc}" + return self.run(command, **kwargs) + + def gplist(self, gap1: str = "", gap2: str = "", ginc: str = "", **kwargs): + r"""Lists the gap conditions. + + Mechanical APDL Command: `GPLIST `_ + + Parameters + ---------- + gap1 : str + List gap conditions from ``GAP1`` to ``GAP2`` ( ``GAP2`` defaults to ``GAP1`` ) in steps of + ``GINC`` (defaults to 1). If ``GAP1`` = ALL (default), ``GAP2`` and ``GINC`` are ignored and all + gap conditions are listed. + + gap2 : str + List gap conditions from ``GAP1`` to ``GAP2`` ( ``GAP2`` defaults to ``GAP1`` ) in steps of + ``GINC`` (defaults to 1). If ``GAP1`` = ALL (default), ``GAP2`` and ``GINC`` are ignored and all + gap conditions are listed. + + ginc : str + List gap conditions from ``GAP1`` to ``GAP2`` ( ``GAP2`` defaults to ``GAP1`` ) in steps of + ``GINC`` (defaults to 1). If ``GAP1`` = ALL (default), ``GAP2`` and ``GINC`` are ignored and all + gap conditions are listed. + + Notes + ----- + + .. _GPLIST_notes: + + This command is valid in any processor. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = f"GPLIST,{gap1},{gap2},{ginc}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/_nonlinear_options.py b/src/ansys/mapdl/core/_commands/solution/_nonlinear_options.py new file mode 100644 index 00000000000..23a55e17b7c --- /dev/null +++ b/src/ansys/mapdl/core/_commands/solution/_nonlinear_options.py @@ -0,0 +1,64 @@ +# 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 NonlinearOptions: + + def crplim(self, crcr: str = "", option: str = "", **kwargs): + r"""Specifies the creep criterion for automatic time stepping. + + Mechanical APDL Command: `CRPLIM `_ + + Parameters + ---------- + crcr : str + Value of creep criteria for the creep limit ratio control. + + option : str + Type of creep analysis for which the creep limit ratio is specified : + + * ``1 (or ON)`` - Implicit creep analysis. + + * ``0 (or OFF)`` - Explicit creep analysis. + + Notes + ----- + + .. _CRPLIM_notes: + + The :ref:`cutcontrol` command can also be used to set the creep criterion and is preferred over this + command for setting automatic time step controls. + + The creep ratio control can be used at the same time for implicit creep and explicit creep analyses. + For implicit creep ( ``Option`` = 1), the default value of ``CRCR`` is zero (that is, no creep limit + control), and you can specify any value. For explicit creep ( ``Option`` = 0), the default value of + ``CRCR`` is 0.1, and the maximum value allowed is 0.25. + + This command is also valid in PREP7. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = f"CRPLIM,{crcr},{option}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/all_others.py b/src/ansys/mapdl/core/_commands/solution/_status.py similarity index 53% rename from src/ansys/mapdl/core/_commands/solution/all_others.py rename to src/ansys/mapdl/core/_commands/solution/_status.py index b55dfdc0127..93726093937 100644 --- a/src/ansys/mapdl/core/_commands/solution/all_others.py +++ b/src/ansys/mapdl/core/_commands/solution/_status.py @@ -19,3 +19,32 @@ # 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 gap(self, **kwargs): + r"""Specifies "mode-superposition transient gap conditions" as the subsequent status topic. + + Mechanical APDL Command: `GAP `_ + + Notes + ----- + + .. _GAP_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. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = "GAP" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/additive_manufacturing.py b/src/ansys/mapdl/core/_commands/solution/additive_manufacturing.py new file mode 100644 index 00000000000..e4064b44532 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/solution/additive_manufacturing.py @@ -0,0 +1,588 @@ +# 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 AdditiveManufacturing: + + def ambeam(self, numbeams: str = "", **kwargs): + r"""For multiple-beam printers, specifies the number of beams in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMBEAM `_ + + Parameters + ---------- + numbeams : str + Number of beams used in the build process. Default = 1. + + Notes + ----- + + .. _AMBEAM_notes: + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMBEAM,{numbeams}" + return self.run(command, **kwargs) + + def ambuild( + self, + option: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + **kwargs, + ): + r"""Specifies printer parameters for the build and other options in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMBUILD `_ + + Parameters + ---------- + option : str + Option: + + * ``LAYERT`` - ``VAL1`` - Deposition-layer thickness. + + ``VAL2`` - Mesh height. + + ``VAL3`` - Error-checking flag. Set to 0 (default) or 1. Setting to 1 causes the application to omit + error checks for consistent element size and elements spanning across layers. + + * ``SCAN`` - ``VAL1`` - Hatch spacing. + + ``VAL2`` - Beam-travel speed. + + * ``TIME`` - ``VAL1`` - Inter-layer dwell time. Default = 0.0. + + ``VAL2`` - Dwell-time multiplier for multiple parts on the build plate or number of repeated + symmetry sectors in simulations with symmetry. Default = 1.0. + + ``VAL3`` - Unused field. + + ``VAL4`` - Scan time table. + + * ``PLATE`` - ``VAL1`` - Z-coordinate of the top of the build plate. Default = 0.0. + + * ``CHECK`` - ``VAL1`` - If YES, create the build-summary file but do not solve. Default = NO. + + * ``RTHFILE`` - ``VAL1`` - Name of the thermal-results file (including its path). Default = + :file:`file.rth` in the current working directory. + + * ``SSF`` - ``VAL1`` - Strain Scaling Factor. Default = 1.0. + + val1 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val3 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val4 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + Notes + ----- + + .. _AMBUILD_notes: + + If using a layered tetrahedral mesh, specify the mesh height (LAYERT, ``VAL2`` ). For Cartesian + meshes, the mesh height is determined automatically. + + When setting the error-checking flag (LAYERT,,,1), verify your model and results carefully. Using + the flag may lead to improper setup of layers or boundary conditions. + + The hatch spacing and beam travel speed are the average values used during the build. + + The inter-layer dwell time (TIME, ``VAL1`` ) is the span of time from the end of the deposition of a + layer to the start of the deposition of the next layer. It includes the time required for recoater- + blade repositioning and powder-layer spreading. + + The dwell-time multiplier (TIME, ``VAL2`` ) accounts for more than one part being printed on the + build plate, or it is used to reconcile build time in simulations using symmetry. For multiple parts + on a build plate, if the additional parts are the same part as the one being simulated and are + arranged in the same orientation on the build plate, the multiplier is the total number of parts. If + different parts exist on the plate, the multiplier is an estimate of the time required to build the + other parts relative to the part being simulated. In simulations with symmetry, the dwell-time + multiplier is the total number of repeated symmetry sectors: 2 for half symmetry, 4 for ¼ symmetry, + and so on. + + The scan time (TIME, ``VAL4`` ) represents the amount of time it takes to scan a real layer. By + default, the scan time will be determined from each layer``s cross-sectional area and other process + parameters. When specified, it must be defined as a table with times specified on the Z primary + variable. Times that are averaged or interpolated from the table should not include recoating time + and will be adjusted to account for superlayer size compared to the deposition thickness. + + When specifying the name of the thermal-results file (RTHFILE, ``VAL1`` ), omit the :file:`.rth` + extension. The program also looks for the :file:`thermal.build` file in the same path. + + The strain scaling factor (SSF, ``VAL1`` ) scales the thermal strains in the structural portion of + thermal-structural simulations by the specified value. + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMBUILD,{option},{val1},{val2},{val3},{val4}" + return self.run(command, **kwargs) + + def amenv(self, tgas: str = "", hgas: str = "", **kwargs): + r"""Specifies the build-environment thermal boundary conditions in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMENV `_ + + Parameters + ---------- + tgas : str + Temperature of the gas in the build enclosure. + + hgas : str + Convection coefficient from the part to the enclosure gas. + + Notes + ----- + + .. _AMENV_notes: + + If using the power-bed fusion process ( :ref:`amtype`,PBF), the convection is applied only to the + top of a newly laid layer. + + If using the directed-energy deposition process ( :ref:`amtype`,DED), the convection is applied to + the top of a newly laid layer and to the sides of the part already built. + + No convection boundary conditions are applied to the plate, although you can define them manually ( + :ref:`sf` and related commands). + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMENV,{tgas},{hgas}" + return self.run(command, **kwargs) + + def ammat(self, matpart: str = "", tmelt: str = "", trelax: str = "", **kwargs): + r"""Specifies the melting and relaxation temperatures of the build material in an `additive + manufacturing `_ + analysis. + + Mechanical APDL Command: `AMMAT `_ + + Parameters + ---------- + matpart : str + The material ID of the build part. Default = 1. + + tmelt : str + Melting temperature of the build part (required). + + trelax : str + Relaxation temperature of the build part (optional). + + Notes + ----- + + .. _AMMAT_notes: + + This command is required in an additive manufacturing analysis. + + If the part consists of multiple material IDs, you can specify any of the material IDs ( ``MATPART`` + ), as all are of the same material. + + The melting temperature ( ``TMELT`` ) is the temperature at which thermal strains begin to + accumulate. This value is typically the liquidus-to-solidus temperature, but may be less for some + phase-transition material (such as Ti64). + + The relaxation temperature ( ``TRELAX`` ) is the temperature at which the strains are zeroed out + (annealed). You can use ``TRELAX`` during the build process ( :ref:`amstep`,BUILD) to account for + stress relaxation, but it serves primarily as a simplified stress-relaxation method during the heat- + treat step ( :ref:`amstep`,HEATTREAT). (A creep model offers a more stringent stress-relaxation + approach if needed.) + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMMAT,{matpart},{tmelt},{trelax}" + return self.run(command, **kwargs) + + def ampowder( + self, tpowder: str = "", hpowder: str = "", matfactor: str = "", **kwargs + ): + r"""Specifies the thermal conditions of the powder in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMPOWDER `_ + + Parameters + ---------- + tpowder : str + Temperature of the newly added powder. + + hpowder : str + Effective convection coefficient from the part to the powder bed. + + matfactor : str + Knockdown factor applied to the solid material properties (to obtain the powder material + properties). Default = 0.01. + + Notes + ----- + + .. _AMPOWDER_notes: + + This command applies only to the powder-bed fusion ( :ref:`amtype`,PBF) process. + + To estimate the convection coefficient ( ``HPOWDER`` ), divide the conduction property of the powder + (its KXX) by a characteristic conduction length into the powder (for example, ¼ of the distance from + the part boundary to the build-chamber wall). + + The program uses the knockdown factor ( ``MATFACTOR`` ) to estimate the powder properties. The + program applies the factor (typically 0.01) to the solid material properties to estimate the + properties of the material in its powder state. The powder-state properties are used during the + heating of the new layer (before its subsequent solidification and cooldown) prior to the next layer + being applied. + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMPOWDER,{tpowder},{hpowder},{matfactor}" + return self.run(command, **kwargs) + + def amresult(self, item: str = "", key: str = "", **kwargs): + r"""Specifies `additive manufacturing + `_ result data + written to a :file:`.txt` None file. + + Mechanical APDL Command: `AMRESULT `_ + + Parameters + ---------- + item : str + Result item to output to a tab-delimited :file:`.txt` file: + + * ``RINT`` - Recoater interference. Available in a structural additive manufacturing analysis only. + + * ``DTEMP`` - Layer end temperature. Available in a thermal additive manufacturing analysis only. + + * ``HSTN`` - High Strain. Available in a structural additive manufacturing analysis only. + + key : str + Write-control key: + + * ``OFF`` - Does not write the specified result item (default). + + * ``ON`` - Writes the specified result item. + + Notes + ----- + + .. _AMRESULT_notes: + + This command controls `additive manufacturing + `_ result data + written to a :file:`.txt` file. Specifically, :file:`AMResults.txt` is written for recoater + interference and layer end temperature, and :file:`AMHighStrain.txt` is written for high strains. + The specified results are not written to the database results ( :file:`.RST` ) file. + + Result items written to the :file:`.txt` file also include node numbers and x, y, z locations. + + RINT gives the z-deformation of a layer just before a new layer is applied. This result value can + help to determine whether an issue may occur when spreading a new layer. + + DTEMP gives the temperature of a layer just before a new layer is applied. This result value can + help to identify regions where the build may be overheating that may result in problematic thermal + conditions. + + HSTN gives the maximum equivalent strain experienced during the build process. This result value can + help to identify regions at risk of cracking. + """ + command = f"AMRESULT,{item},{key}" + return self.run(command, **kwargs) + + def amstep( + self, + sequence: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + **kwargs, + ): + r"""Specifies the process-sequence steps in an additive manufacturing analysis. + + Mechanical APDL Command: `AMSTEP `_ + + Parameters + ---------- + sequence : str + One of the following sequence options: + + * ``PREHEAT`` - ``VAL1`` - Preheat temperature of the build plate. Default = :ref:`tunif`. + + * ``BUILD`` - ``VAL1`` - Unused. + + ``VAL2`` - Ending-layer number (for performing the simulation from the first layer to the specified + layer only). Default = last layer necessary to build the part. + + ``VAL3`` - Number of time steps taken to apply heating. Default = 2. + + ``VAL4`` - Number of time steps taken between layer additions. Default = 2. + + ``VAL5`` - Unused. + + ``VAL6`` - Bias growth factor for time steps between layer additions. Default = 1. + + * ``COOLDOWN`` - ``VAL1`` - Ambient (room) temperature (to serve as the target cooldown + temperature). + + ``VAL2`` - Cooldown time. If 0 or unspecified, the program calculates the time based on the volume + of the part and the convection coefficient ( :ref:`amenv` and :ref:`ampowder` ). + + ``VAL3`` - Number of time steps taken to cool down. Default = 20. + + * ``HEATTREAT`` - Perform a heat-treat (stress-relief) step. + + * ``REMOVE`` - ``VAL1`` - The number of a support to remove. Specify 0 for plate. + + ``VAL2`` - Directional cutoff step size. Only valid if ``VAL1`` = 0. + + ``VAL3`` - Directional cutoff angle specified on the X-Y plane from the +X axis. Only valid if + ``VAL1`` = 0. Default = 0 radians. + + * ``USER`` - Perform a user-defined step. + + val1 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val3 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val4 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val5 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + val6 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + Notes + ----- + + .. _AMSTEP_notes: + + :ref:`amstep` executes a process-sequence step: + + * In a thermal analysis, ``Sequence`` = PREHEAT sets the value of the starting temperature of the + build plate. It is ignored in a structural analysis. + + * ``Sequence`` = BUILD executes the layer-by-layer build sequence. + + * ``Sequence`` = COOLDOWN executes the cooldown step and must occur after the BUILD step. + + * ``Sequence`` = HEATTREAT performs a heat-treatment step to stress-relieve the part. Issue + :ref:`ambuild`,RTHFILE to point to the heat-treat thermal-cycle results and specify either a + relaxation temperature ( :ref:`ammat` ) or creep properties ( :ref:`tb` ). + + * In a structural analysis, ``Sequence`` = REMOVE removes the requested support or build plate. It + is ignored in a thermal analysis. + + * In a structural analysis, ``Sequence`` = USER can specify an initial step (such as bolt-pretension + the build plate) or a final step (such as a manufacturing postprocessing step). + + For ``Sequence`` = BUILD and ``Sequence`` = COOLDOWN, the number of time steps specified determines + the accuracy of the captured temperature profile. For distortion and global residual stresses, the + default is usually sufficient. With some materials (Al alloys in particular), the default of evenly + spaced time steps during the build ( ``Sequence`` = BUILD) may not adequately capture the cooldown. + The bias growth factor ( ``VAL6`` ) adjusts the time spacing to better resolve temperatures as they + cool between layers. + + For ``Sequence`` = REMOVE, directional cutoff is activated when ``VAL1`` is set to 0 (plate), and a + value is given for ``VAL2`` (cut step size). This option will sequentially remove the first layer of + elements in a series of steps with each step moving the specified distance ( ``VAL2`` ). The cutoff + steps will continue across the entire part in the direction of the specified angle ( ``VAL3`` ). If + neither ``VAL1`` nor ``VAL2`` are specified, the entire base is removed in a single instantaneous + step. + + When ``Sequence`` = USER, the process-sequence steps are bypassed, and the usual nonlinear solution + is performed during this step. All applicable load and load step options are accessible. If USER is + the initial step, all times are offset by the TIME associated with the USER step. + + This command starts a solution. You must remain in SOLUTION between sequence steps. + + This command is valid in the SOLUTION processor only. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + + **Product Restrictions** + + .. _AMSTEPprodrest: + + Ansys Mechanical Enterprise PrepPost This command is not valid. + """ + command = f"AMSTEP,{sequence},{val1},{val2},{val3},{val4},{val5},{val6}" + return self.run(command, **kwargs) + + def amsupports( + self, nsupports: str = "", compname: str = "", sectarray: str = "", **kwargs + ): + r"""Specifies information about the supports in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMSUPPORTS `_ + + Parameters + ---------- + nsupports : str + Number of supports. + + compname : str + Root name of the components containing the elements comprising each support. (For example, if + ``CompName`` = "MySupport," MySupport1 represents support 1, MySupport2 represents support 2, + etc.) + + sectarray : str + Name of the array ( :ref:`dim` ) containing the section-reference ID for each support. + + Notes + ----- + + .. _AMSUPPORTS_notes: + + The section-reference ID array ( ``SectArray`` ) is ``NSUPPORTS`` long, with each array member + representing a section-reference ID of a corresponding support. + + :ref:`sectype` specifies the type of support, and :ref:`secdata` specifies the geometry of the + support. + + **Example: Specifying Support Information in an Additive Manufacturing Analysis** + + .. code:: apdl + + ! specify supports + *dim,suppsect,,2 ! two supports + suppsect(1)=101 ! support 1 sectID=101 + suppsect(2)=101 ! support 2 sectID=101 + ! + sectype,101,support,block ! sectype is a block support + secdata,.07,1 ! wall thickness and spacing + amsupport,2,support,suppsect ! root name is "support" and suppsect is the + ! array name containing the section IDs + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMSUPPORTS,{nsupports},{compname},{sectarray}" + return self.run(command, **kwargs) + + def amtype(self, process: str = "", **kwargs): + r"""Specifies the printing process in an `additive manufacturing + `_ analysis. + + Mechanical APDL Command: `AMTYPE `_ + + Parameters + ---------- + process : str + Process option: + + * ``PBF`` - Powder-bed fusion process. + + * ``DED`` - Directed-energy deposition process. + + Notes + ----- + + .. _AMTYPE_notes: + + The powder-bed fusion (PBF) process uses thermal energy from a laser or electron beam to selectively + fuse powder in a powder bed. + + The directed-energy deposition (DED) process uses thermal energy, typically from a laser, to fuse + materials by melting them as they are deposited. + + This command is also valid in PREP7. + + For more information, including a list of the elements and commands used in an additive + manufacturing analysis, see `AM Process Simulation in Workbench Additive + `_ + """ + command = f"AMTYPE,{process}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/analysis_2d_to_3d.py b/src/ansys/mapdl/core/_commands/solution/analysis_2d_to_3d.py new file mode 100644 index 00000000000..3b450f1e106 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/solution/analysis_2d_to_3d.py @@ -0,0 +1,78 @@ +# 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 Analysis2DTo3D: + + def map2dto3d(self, action: str = "", value1: str = "", value2: str = "", **kwargs): + r"""Initiates a 2D to 3D analysis and maps variables. + + Mechanical APDL Command: `MAP2DTO3D `_ + + Parameters + ---------- + action : str + The 2D to 3D analysis action to perform: + + * ``START`` - Start the analysis process by rebuilding the 2D analysis database ( :file:`.db` ) based on the + specified load step and substep information, and update nodes to their deformed positions in the 2D + mesh. + + * ``VALUE1`` - The load step number at which 2D to 3D analysis should occur. The default value is + the highest load step number found in the :file:`Jobname.Rnnn` files (for the current jobname and in + the current directory). + + * ``VALUE2`` - The substep number of the specified load step ( ``VALUE1`` ) at which the 2D to 3D + analysis should occur. The default value is the highest substep number found in the specified load + step in the :file:`Jobname.Rnnn` files (for the current jobname and in the current directory). + + * ``FINISH`` - Maps boundary conditions and loads from the 2D mesh to the extruded 3D mesh. ( VALUE1 + and VALUE2 are not used.) + + * ``SOLVE`` - Map nodal and element solutions from 2D to 3D and rebalance the results. + + * ``VALUE1`` - The maximum number of substeps allowed during rebalancing. Default = 500. + + value1 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + value2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for + further information. + + Notes + ----- + The :ref:`map2dto3d` command initiates the 2D to 3D analysis process, sets analysis options, + rebuilds the database, and maps the solution variables from the 2D mesh to the 3D mesh. + + Before issuing this command, clear the database ( :ref:`clear` ). + + For more information, see `2D to 3D Analysis + `_ + """ + command = f"MAP2DTO3D,{action},{value1},{value2}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/analysis_options.py b/src/ansys/mapdl/core/_commands/solution/analysis_options.py index 90cbbec21a9..cf37ea66a92 100644 --- a/src/ansys/mapdl/core/_commands/solution/analysis_options.py +++ b/src/ansys/mapdl/core/_commands/solution/analysis_options.py @@ -20,3719 +20,4476 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -from typing import Optional - -from ansys.mapdl.core.mapdl_types import MapdlInt - class AnalysisOptions: - def abextract(self, mode1="", mode2="", **kwargs): - """Extracts the alpha-beta damping multipliers for Rayleigh damping. - APDL Command: ABEXTRACT + def abextract(self, mode1: str = "", mode2: str = "", **kwargs): + r"""Extracts the alpha-beta damping multipliers for Rayleigh damping. + + Mechanical APDL Command: `ABEXTRACT `_ Parameters ---------- - mode1 + mode1 : str First mode number. - mode2 + mode2 : str Second mode number. Notes ----- - ABEXTRACT calls the command macro DMPEXT to extract the damping ratio - of MODE1 and MODE2 and then computes the Alpha and Beta damping - multipliers for use in a subsequent structural harmonic or transient - analysis. See Damping in the Structural Analysis Guide for more - information on the alpha and beta damping multipliers. The damping - multipliers are stored in parameters ALPHADMP and BETADMP and can be - applied using the ALPHAD and BETAD commands. Before calling ABEXTRACT, - you must issue RMFLVEC to extract the modal displacements. In addition, - a node component FLUN must exist from all FLUID136 nodes. See - Introduction for more information on thin film analyses. - This command is also valid in PREP7. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + .. _ABEXTRACT_notes: + + :ref:`abextract` calls the command macro :ref:`dmpext` to extract the damping ratio of ``MODE1`` and + ``MODE2`` and then computes the Alpha and Beta damping multipliers for use in a subsequent + structural harmonic or transient analysis. See `Damping + `_ in + the `Structural Analysis Guide + `_ for more + information on the alpha and beta damping multipliers. The damping multipliers + are stored in parameters ALPHADMP and BETADMP and can be applied using the :ref:`alphad` and + :ref:`betad` commands. Before calling :ref:`abextract`, you must issue :ref:`rmflvec` to extract the + modal displacements. In addition, a node component FLUN must exist from all ``FLUID136`` nodes. See + for more information on thin film analyses. + + This command is also valid in PREP7. Distributed-Memory Parallel (DMP) Restriction This command is + not supported in a DMP solution. """ command = f"ABEXTRACT,{mode1},{mode2}" return self.run(command, **kwargs) - def accoption(self, activate="", **kwargs): - """Specifies GPU accelerator capability options. + def accoption(self, activate: str = "", **kwargs): + r"""Specifies GPU accelerator capability options. - APDL Command: ACCOPTION + Mechanical APDL Command: `ACCOPTION `_ Parameters ---------- - activate - Activates the GPU accelerator capability within the equation - solvers. + activate : str + Activates the GPU accelerator capability within the equation solvers. + + * ``OFF`` - Do not use GPU accelerator. - Do not use GPU accelerator. - Use GPU accelerator. + * ``ON`` - Use GPU accelerator. Notes ----- - The GPU accelerator capability requires specific hardware to be - installed on the machine. See the appropriate ANSYS, Inc. Installation - Guide (Windows or Linux) for a list of supported GPU hardware. Use of - this capability also requires HPC licensing. For more information, see - GPU Accelerator Capability in the Parallel Processing Guide. - - The GPU accelerator capability is available for the sparse direct - solver and the PCG and JCG iterative solvers. Static, buckling, modal, - full harmonic, and full transient analyses are supported. For buckling - analyses, the Block Lanczos and Subspace eigensolvers are supported. - For modal analyses, only the Block Lanczos, PCG Lanczos, Subspace, - Unsymmetric, and Damped eigensolvers are supported. Activating this - capability when using other equation solvers or other analysis types + + .. warning:: + + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. + + **Argument Descriptions** + + .. _ACCOPTION_argdescript: + + * ``activate : str`` - Activates the GPU accelerator capability within the equation solvers. + + * ``OFF`` - Do not use GPU accelerator. + + * ``ON`` - Use GPU accelerator. + + .. _ACCOPTION_notes: + + The GPU accelerator capability requires specific hardware to be installed on the machine. See the + appropriate Ansys, Inc. Installation Guide ( Windows or Linux ) for a list of supported GPU + hardware. Use of this capability also requires HPC licensing. For more information, see `GPU + Accelerator Capability + `_ + + The GPU accelerator capability is available for the sparse direct solver and the PCG and JCG + iterative solvers. Static, buckling, modal, full harmonic, and full transient analyses are + supported. For buckling analyses, the Block Lanczos and Subspace eigensolvers are supported. For + modal analyses, only the Block Lanczos, PCG Lanczos, Subspace, Unsymmetric, and Damped eigensolvers + are supported. Activating this capability when using other equation solvers or other analysis types has no effect. - The GPU accelerator capability is supported only on the Windows 64-bit - and Linux 64-bit platforms. + The GPU accelerator capability is supported only on the Windows 64-bit and Linux 64-bit platforms. """ command = f"ACCOPTION,{activate}" return self.run(command, **kwargs) - def adams(self, nmodes="", kstress="", kshell="", **kwargs): - """Performs solutions and writes flexible body information to a modal + def adams( + self, + nmodes: str = "", + kstress: int | str = "", + kshell: int | str = "", + **kwargs, + ): + r"""Performs solutions and writes flexible body information to a modal neutral file ( + :file:`Jobname.MNF` ) for use in an ADAMS analysis. - APDL Command: ADAMS - neutral file (Jobname.MNF) for use in an ADAMS analysis. + Mechanical APDL Command: `ADAMS `_ Parameters ---------- - nmodes - Number of normal modes to be written to Jobname.MNF file (no - default). + nmodes : str + Number of normal modes to be written to :file:`Jobname.MNF` file (no default). - kstress + kstress : int or str Specifies whether to write stress or strain results: - 0 - Do not write stress or strain results (default). + * ``0`` - Do not write stress or strain results (default). - 1 - Write stress results. + * ``1`` - Write stress results. - 2 - Write strain results. + * ``2`` - Write strain results. - 3 - Write both stress and strain results. + * ``3`` - Write both stress and strain results. - kshell - Shell element output location. This option is valid only for shell - elements. + kshell : int or str + Shell element output location. This option is valid only for shell elements. - 0, 1 - Shell top surface (default). + * ``0, 1`` - Shell top surface (default). - 2 - Shell middle surface. + * ``2`` - Shell middle surface. - 3 - Shell bottom surface. + * ``3`` - Shell bottom surface. Notes ----- - ADAMS invokes a predefined ANSYS macro that solves a series of analyses - and then writes the modal neutral file, Jobname.MNF. This file can be - imported into the ADAMS program in order to perform a rigid body - dynamics simulation. For detailed information on how to use the ADAMS - command macro to create a modal neutral file, see Rigid Body Dynamics - and the ANSYS-ADAMS Interface in the Substructuring Analysis Guide. - - Before running the ADAMS command macro, you must specify the units with - the /UNITS command. The interface points should be the only selected - nodes when the command macro is initiated. (Interface points are nodes - where constraints may be applied in ADAMS.) Only selected elements will + + .. _ADAMS_notes: + + :ref:`adams` invokes a predefined Mechanical APDL macro that solves a series of analyses and then + writes + the modal neutral file, :file:`Jobname.MNF`. This file can be imported into the ADAMS program in + order to perform a rigid body dynamics simulation. For detailed information about how to use the + :ref:`adams` command macro to create a modal neutral file, see `Rigid Body Dynamics and the Ansys- + Adams Interface + `_ + + Before running the :ref:`adams` command macro, you must specify the units with the :ref:`units` + command. The interface points should be the only selected nodes when the command macro is initiated. + (Interface points are nodes where constraints may be applied in ADAMS.) Only selected elements will be considered in the calculations. - By default, stress and strain data is transferred to the ADAMS program - for all nodes, as specified by the KSTRESS value. If you want to - transfer stress/strain data for only a subset of nodes, select the - desired subset and create a node component named "STRESS" before - running the ADAMS command macro. For example, you may want to select - exterior nodes for the purpose of visualization in the ADAMS program. - - The default filename for the modal neutral file is Jobname.MNF. In - interactive (GUI) mode, you can specify a filename other than - Jobname.MNF. In batch mode, there is no option to change the filename, - and the modal neutral file is always written to Jobname.MNF. + By default, stress and strain data is transferred to the ADAMS program for all nodes, as specified + by the ``KSTRESS`` value. If you want to transfer stress/strain data for only a subset of nodes, + select the desired subset and create a node component named STRESS before running the :ref:`adams` + command macro. For example, you may want to select exterior nodes for the purpose of visualization + in the ADAMS program. + + The default filename for the modal neutral file is :file:`Jobname.MNF`. In interactive (GUI) mode, + you can specify a filename other than :file:`Jobname.MNF`. In batch mode, there is no option to + change the filename, and the modal neutral file is always written to :file:`JobnameMNF`. """ command = f"ADAMS,{nmodes},{kstress},{kshell}" return self.run(command, **kwargs) - def antype(self, antype="", status="", ldstep="", substep="", action="", **kwargs): - """Specifies the analysis type and restart status. + def antype( + self, + antype: str = "", + status: str = "", + ldstep: str = "", + substep: str = "", + action: str = "", + prelp: str = "", + **kwargs, + ): + r"""Specifies the analysis type and restart status. + + Mechanical APDL Command: `ANTYPE `_ + + **Command default:** - APDL Command: ANTYPE + .. _ANTYPE_default: + + New static analysis. Parameters ---------- - antype - Analysis type (defaults to the previously specified analysis type, - or to ``STATIC`` if none specified): - - STATIC or 0 - Perform a **static analysis**. - Valid for all degrees of freedom. - - BUCKLE or 1 - Perform a buckling analysis. - Implies that a previous static solution was performed with - prestress effects calculated - (:meth:`Mapdl.pstres('ON') `). - Valid for structural degrees of freedom only. - - MODAL or 2 - Perform a modal analysis. - Valid for structural and fluid degrees of freedom. - - HARMIC or 3 - Perform a harmonic analysis. - Valid for structural, fluid, magnetic, and electrical degrees - of freedom. - - TRANS or 4 - Perform a transient analysis. - Valid for all degrees of freedom. - - SUBSTR or 7 - Perform a substructure analysis. - Valid for all degrees of freedom. - - SPECTR or 8 - Perform a spectrum analysis. - Implies that a previous modal analysis was - performed. Valid for structural degrees of freedom - only. - - status + antype : str + Analysis type (defaults to the previously specified analysis type, or to STATIC if none specified): + + * ``STATIC or 0`` - Perform a static analysis. Valid for all degrees of freedom. + + * ``BUCKLE or 1`` - Perform a buckling analysis. Implies that a previous static solution was + performed with prestress effects calculated ( :ref:`pstres`,ON). Valid for structural degrees of + freedom only. + + * ``MODAL or 2`` - Perform a modal analysis. Valid for structural and fluid degrees of freedom. + + * ``HARMIC or 3`` - Perform a harmonic analysis. Valid for structural, fluid, magnetic, and + electrical degrees of freedom. + + * ``TRANS or 4`` - Perform a transient analysis. Valid for all degrees of freedom. + + * ``SUBSTR or 7`` - Perform a substructure analysis. Valid for all degrees of freedom. + + * ``SPECTR or 8`` - Perform a spectrum analysis. Implies that a previous modal analysis was + performed. Valid for structural degrees of freedom only. + + * ``SOIL or 9`` - Perform a soil analysis including geostatic stress equilibrium or consolidation. + Valid for structural and fluid-pore-pressure degrees of freedom. + + status : str Specifies the status of the analysis (new or restart): - NEW - Specifies a new analysis (default). If ``NEW``, the remaining fields on this - command are ignored. - - RESTART - Specifies a restart of a previous analysis. Valid for static, modal, and - transient (full or mode-superposition method) analyses. - For more information about restarting static and - transient analyses, see Multiframe Restart in the Basic - Analysis Guide. For more information on restarting a - modal analysis, see Modal Analysis Restart in the Basic - Analysis Guide. - - Multiframe restart is also valid for harmonic analysis, but is limited - to 2-D magnetic analysis only. - - A substructure analysis (`backsubstitution` method only) can be restarted for the - purpose of generating additional load vectors. For more information, see the - :meth:`Mapdl.seopt() ` command and - Applying Loads and Creating the Superelement - Matrices in the Substructuring Analysis Guide. - - VTREST - Specifies the restart of a previous VT Accelerator analysis. Valid only with - ``Antype = STATIC``, ``HARMIC``, or ``TRANS``. For more information, - see VT Accelerator Re-run in the Basic Analysis Guide. - - ldstep + * ``NEW`` - Specifies a new analysis (default). If NEW, the remaining fields on this command are + ignored. + + * ``RESTART`` - Specifies a restart of a previous analysis. Valid for static, modal, and transient + (full or mode- superposition method) analyses. For more information about restarting static and + transient analyses, see `Multiframe Restart + `_ + `Modal Analysis Restart + `_ + + Multiframe restart is also valid for harmonic analysis, but is limited to 2D magnetic analysis only. + + A substructure analysis (backsubstitution method only) can be restarted for the purpose of + generating additional load vectors. For more information, see the :ref:`seopt` command and `Applying + Loads and Creating the Superelement Matrices + `_ + + ldstep : str Specifies the load step at which a multiframe restart begins. - substep + For full transient and nonlinear static analyses, the default is the highest load step number + found in the :file:`Jobname.Rnnn` files for the current jobname in the current directory. + + For mode-superposition transient analyses, the default is none. + + substep : str Specifies the substep at which a multiframe restart begins. - action + For full transient and nonlinear static analyses, the default is the highest substep number + found for the specified ``LDSTEP`` in the :file:`Jobname.Rnnn` files in the current directory. + + For mode-superposition transient analyses, the default is none. + + action : str Specifies the manner of a multiframe restart. - CONTINUE - The program continues the analysis based on the specified - ``LDSTEP`` and ``SUBSTEP`` (default). The current load step is continued. - If the end of the load step is encountered in the ``.Rnnn`` file, a - new load step is started. The program deletes all ``.Rnnn`` - files, or ``.Mnnn`` files for mode-superposition transient - analyses, beyond the point of restart and updates the - ``.LDHI`` file if a new load step is encountered. - - ENDSTEP - At restart, force the specified load step (``LDSTEP``) to end at the specified - substep (``SUBSTEP``), even though the end of the current - load step has not been reached. At the end of the - specified substep, all loadings are scaled to the level - of the current ending and stored in the ``.LDHI`` file. A run - following this ``ENDSTEP`` starts a new load step. This - capability allows you to change the load level in the - middle of a load step. The program updates the ``.LDHI`` file - and deletes all .Rnnn files, or ``.Mnnn`` files for mode- - superposition transient analyses, beyond the point of - ``ENDSTEP``. The ``.Rnnn`` or ``.Mnnn`` file at the point of ``ENDSTEP`` - are rewritten to record the rescaled load level. - - RSTCREATE - At restart, retrieve information to be written to the results file for the - specified load step (``LDSTEP``) and substep (``SUBSTEP``). Be - sure to use :meth:`Mapdl.outres() ` - to write the results to the - results file. This action does not affect the ``.LDHI`` or - ``.Rnnn`` files. Previous items stored in the results file - at and beyond the point of ``RSTCREATE`` are deleted. This - option cannot be used to restart a mode-superposition - transient analysis. - - PERTURB - At restart, a linear perturbation analysis (static, modal, buckling, or full - harmonic) is performed for the specified load step - (``LDSTEP``) and substep (``SUBSTEP``). This action does not - affect the ``.LDHI``, ``.Rnnn``, or ``.RST`` files. + * ``CONTINUE`` - The program continues the analysis based on the specified ``LDSTEP`` and + ``SUBSTEP`` (default). The current load step is continued. If the end of the load step is + encountered in the :file:`.Rnnn` file, a new load step is started. The program deletes all + :file:`.Rnnn` files, or :file:`.Mnnn` files for mode-superposition transient analyses, beyond the + point of restart and updates the :file:`.LDHI` file if a new load step is encountered. + + * ``ENDSTEP`` - At restart, force the specified load step ( ``LDSTEP`` ) to end at the specified + substep ( ``SUBSTEP`` ), even though the end of the current load step has not been reached. At the + end of the specified substep, all loadings are scaled to the level of the current ending and stored + in the :file:`.LDHI` file. A run following this ENDSTEP starts a new load step. This capability + allows you to change the load level in the middle of a load step. The program updates the + :file:`.LDHI` file and deletes all :file:`.Rnnn` files, or :file:`.Mnnn` files for mode- + superposition transient analyses, beyond the point of ENDSTEP. The :file:`.Rnnn` or :file:`.Mnnn` + file at the point of ENDSTEP are rewritten to record the rescaled load level. + + * ``RSTCREATE`` - At restart, retrieve information to be written to the results file for the + specified load step ( ``LDSTEP`` ) and substep ( ``SUBSTEP`` ). Be sure to use :ref:`outres` to + write the results to the results file. This action does not affect the :file:`.LDHI` or + :file:`.Rnnn` files. Previous items stored in the results file at and beyond the point of RSTCREATE + are deleted. This option cannot be used to restart a mode-superposition transient analysis. + + * ``PERTURB`` - At restart, a linear perturbation analysis (static, modal, buckling, or full + harmonic) is performed for the specified load step ( ``LDSTEP`` ) and substep ( ``SUBSTEP`` ). This + action does not affect the :file:`.LDHI`, :file:`.Rnnn`, or :file:`.RST` files. + + For a `linear perturbation + `_ analysis, + set ``Action`` = PERTURB; otherwise, the existing restart files, such as the :file:`.LDHI`, + :file:`.Rnnn`, or :file:`.RST` file, may be modified by the linear perturbation analysis. Issue the + :ref:`perturb` command to indicate the desired analysis type (STATIC, MODAL, BUCKLE, HARMONIC, or + SUBSTR ). + + prelp : str + Flag indicating whether a subsequent linear perturbation will be performed: + + * ``YES`` - Specifies the first static analysis with a sequential linear perturbation analysis. + Setting PRELP = YES is necessary for acoustics-structural interaction linear perturbation analysis, + if the :ref:`morph` command with ``StrOpt`` = YES is not issued. + + * ``NO`` - No specification for a subsequent linear perturbation (default). Notes ----- - If using the :meth:`Mapdl.antype() ` - command to change the analysis type in the same - :meth:`Mapdl.solve() ` session, - the program issues the following message: `"Some analysis - options have been reset to their defaults. Please verify current - settings or respecify as required."` Typically, the program resets - commands such as :meth:`Mapdl.nlgeom() ` and - :meth:`Mapdl.eqslv() ` to their default values. - - The analysis type (:meth:`Mapdl.antype() `) - cannot be changed if a restart is specified. - Always save parameters before doing a restart. For more information on - the different types of restart, see Restarting an Analysis in the Basic - Analysis Guide. - - This command is also valid in :meth:`Mapdl.prep7() `. - - The ANSYS Professional - Nonlinear Structural (PRN) product supports - the ``Antype = TRANS`` option for mode-superposition ( - :meth:`Mapdl.trnopt("MSUP") `) analyses - only. + + .. _ANTYPE_notes: + + If using the :ref:`antype` command to change the analysis type in the same SOLVE session, the + program issues the following message: "Some analysis options have been reset to their defaults. + Please verify current settings or respecify as required." Typically, the program resets commands + such as :ref:`nlgeom` and :ref:`eqslv` to their default values. + + If you want to read in view factors after restarting a radiation analysis, issue VFOPT,READ after + ANTYPE,,REST. + + The analysis type ( ``Antype`` ) cannot be changed if a restart is specified. Always save parameters + before doing a restart. For more information on the different types of restart, see `Restarting an + Analysis + `_ + + This command is also valid in PREP7. + + .. _ANTYPE_extranote1: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. """ - command = f"ANTYPE,{antype},{status},{ldstep},{substep},{action}" + command = f"ANTYPE,{antype},{status},{ldstep},{substep},{action},,{prelp}" return self.run(command, **kwargs) - def ascres(self, opt="", **kwargs): - """Specifies the output type for an acoustic scattering analysis. + def ascres(self, opt: str = "", **kwargs): + r"""Specifies the output type for an acoustic scattering analysis. - APDL Command: ASCRES + Mechanical APDL Command: `ASCRES `_ Parameters ---------- - opt + opt : str Output option: - TOTAL - Output the total pressure field (default). + * ``TOTAL`` - Output the total pressure field (default). - SCAT - Output the scattered pressure field. + * ``SCAT`` - Output the scattered pressure field. Notes ----- - Use the ASCRES command to specify the output type for an acoustic - scattering analysis. - The scattered option (Opt = SCAT) provides a scattered pressure output, - psc, required for calculating target strength (TS). + .. _ASCRES_notes: + + Use the :ref:`ascres` command to specify the output type for an acoustic scattering analysis. - The default behavior (Opt = TOTAL) provides a sum of the incident and - scattering fields, ptotal = pinc + psc. + The scattered option ( ``Opt`` = SCAT) provides a scattered pressure output, p:sub:`sc`, required + for calculating target strength (TS). - Issue the AWAVE command to define the incident pressure pinc. If the - AWAVE command is defined with Opt2 = INT, only the total pressure field - is output regardless of the ASCRES,Opt command. + The default behavior ( ``Opt`` = TOTAL) provides a sum of the incident and scattering fields, p + :sup:`total` = p :sup:`inc` + p :sup:`sc`. + + Issue the :ref:`awave` command to define the incident pressure p :sup:`inc`. If the :ref:`awave` + command is defined with ``Opt2`` = INT, only the total pressure field is output regardless of the + :ref:`ascres`, ``Opt`` command. """ command = f"ASCRES,{opt}" return self.run(command, **kwargs) - def asol(self, lab="", opt="", **kwargs): - """Specifies the output type of an acoustic scattering analysis. + def asol(self, lab: str = "", opt: str = "", **kwargs): + r"""Specifies the acoustic solver with scattered field formulation. - APDL Command: ASOL + Mechanical APDL Command: `ASOL `_ Parameters ---------- - lab + lab : str Acoustic solver specification (no default): - SCAT - Set acoustic solver to the scattered field formulation. + * ``SCAT`` - Set acoustic solver to the scattered field formulation. - opt + opt : str Option identifying an acoustic solver status: - OFF - Deactivate the specified acoustic solver (default). + * ``OFF`` - Deactivate the specified acoustic solver (default). - ON - Activate the specified acoustic solver. + * ``ON`` - Activate the specified acoustic solver. Notes ----- - Use the ASOL command to activate the specified acoustic solution - process. - The scattered option (Lab = SCAT) sets the acoustic solver to the - scattered-pressure field formulation. + .. _ASOL_notes: + + Use the :ref:`asol` command to activate the specified acoustic solution process. - Issue the AWAVE command to define the incident pressure pinc. If the - AWAVE command is defined with Opt2 = INT, the acoustic solver is set to - the scattered field formulation regardless of the ASOL command issued. + The scattered option ( ``Lab`` = SCAT) sets the acoustic solver to the scattered-pressure field + formulation. + + Issue the :ref:`awave` command to define the incident pressure p :sup:`inc`. If the :ref:`awave` + command is defined with ``Opt2`` = INT, the acoustic solver is set to the scattered field + formulation regardless of the :ref:`asol` command issued. """ command = f"ASOL,{lab},{opt}" return self.run(command, **kwargs) - def bcsoption(self, memory_option="", memory_size="", solve_info="", **kwargs): - """Sets memory option for the sparse solver. + def bcsoption( + self, + memory_option: str = "", + memory_size: str = "", + solve_info: str = "", + **kwargs, + ): + r"""Sets memory option for the sparse solver. + + Mechanical APDL Command: `BCSOPTION `_ - APDL Command: BCSOPTION + **Command default:** + + .. _BCSOPTION_default: + + Automatic memory allocation is used. Parameters ---------- - memory_option + + memory_option : str Memory allocation option: - DEFAULT - Use the default memory allocation strategy for - the sparse solver. The default strategy attempts - to run in the ``INCORE`` memory mode. If there is - not enough available physical memory when the - solver starts to run in the ``INCORE`` memory mode, - the solver will then attempt to run in the - ``OUTOFCORE`` memory mode. - - INCORE - Use a memory allocation strategy in the sparse - solver that will attempt to obtain enough memory - to run with the entire factorized matrix in - memory. This option uses the most amount of - memory and should avoid doing any I/O. By - avoiding I/O, this option achieves optimal solver - performance. However, a significant amount of - memory is required to run in this mode, and it is - only recommended on machines with a large amount - of memory. If the allocation for in-core memory - fails, the solver will automatically revert to - out-of-core memory mode. - - OUTOFCORE - Use a memory allocation strategy in the sparse - solver that will attempt to allocate only - enough work space to factor each individual - frontal matrix in memory, but will store the - entire factorized matrix on disk. Typically, - this memory mode results in poor performance - due to the potential bottleneck caused by the - I/O to the various files written by the - solver. - - FORCE - This option, when used in conjunction with the - ``Memory_Size`` option, allows you to force the sparse - solver to run with a specific amount of - memory. This option is only recommended for the - advanced user who understands sparse solver memory - requirements for the problem being solved, - understands the physical memory on the system, and - wants to control the sparse solver memory usage. - - memory_size - Initial memory size allocation for the sparse solver in - MB. This argument allows you to tune the sparse solver - memory and is not generally required. Although there is no - upper limit for ``Memory_Size``, the ``Memory_Size`` setting - should always be well within the physical memory - available, but not so small as to cause the sparse solver - to run out of memory. Warnings and/or errors from the - sparse solver will appear if this value is set too low. If - the FORCE memory option is used, this value is the amount - of memory allocated for the entire duration of the sparse - solver solution. - - solve_info + * ``DEFAULT`` - Use the default memory allocation strategy for the sparse solver. The default + strategy attempts to run in the INCORE memory mode. If there is not enough available physical memory + when the solver starts to run in the INCORE memory mode, the solver will then attempt to run in the + OUTOFCORE memory mode. + + * ``INCORE`` - Use a memory allocation strategy in the sparse solver that will attempt to obtain + enough memory to run with the entire factorized matrix in memory. This option uses the most amount + of memory and should avoid doing any I/O. By avoiding I/O, this option achieves optimal solver + performance. However, a significant amount of memory is required to run in this mode, and it is only + recommended on machines with a large amount of memory. If the allocation for in-core memory fails, + the solver will automatically revert to out-of-core memory mode. + + * ``OUTOFCORE`` - Use a memory allocation strategy in the sparse solver that will attempt to + allocate only enough work space to factor each individual frontal matrix in memory, but will store + the entire factorized matrix on disk. Typically, this memory mode results in poor performance due to + the potential bottleneck caused by the I/O to the various files written by the solver. + + * ``FORCE`` - This option, when used in conjunction with the ``Memory_Size`` option, allows you to + force the sparse solver to run with a specific amount of memory. This option is only recommended for + the advanced user who understands sparse solver memory requirements for the problem being solved, + understands the physical memory on the system, and wants to control the sparse solver memory usage. + + memory_size : str + Initial memory size allocation for the sparse solver in GB. This argument allows you to tune the + sparse solver memory and is not generally required. Although there is no upper limit for + ``Memory_Size``, the ``Memory_Size`` setting should always be well within the physical memory + available, but not so small as to cause the sparse solver to run out of memory. Warnings and/or + errors from the sparse solver will appear if this value is set too low. If the FORCE memory + option is used, this value is the amount of memory allocated for the entire duration of the + sparse solver solution. + + solve_info : str Solver output option: - OFF - Turns off additional output printing from the sparse - solver (default). + * ``OFF`` - Turns off additional output printing from the sparse solver (default). - PERFORMANCE - Turns on additional output printing from the - sparse solver, including a performance - summary and a summary of file I/O for the - sparse solver. Information on memory usage - during assembly of the global matrix (that - is, creation of the Jobname.FULL file) is - also printed with this option. + * ``PERFORMANCE`` - Turns on additional output printing from the sparse solver, including a + performance summary and a summary of file I/O for the sparse solver. Information on memory usage + during assembly of the global matrix (that is, creation of the :file:`Jobname.FULL` file) is also + printed with this option. Notes ----- - This command controls options related to the sparse solver in - all analysis types where the sparse solver can be used. It - also controls the Block Lanczos eigensolver in a modal or - buckling analysis. - - The sparse solver runs from one large work space (that is, one - large memory allocation). The amount of memory required for - the sparse solver is unknown until the matrix structure is - preprocessed, including equation reordering. The amount of - memory allocated for the sparse solver is then dynamically - adjusted to supply the solver what it needs to compute the - solution. - - If you have a very large memory system, you may want to try - selecting the ``INCORE`` memory mode for larger jobs to improve - performance. When running the sparse solver on a machine with - very slow I/O performance (for example, slow hard drive - speed), you may want to try using the ``INCORE`` memory mode to - achieve better performance. However, doing so may require much - more memory compared to running in the ``OUTOFCORE`` memory mode. - - Running with the ``INCORE`` memory mode is best for jobs which - comfortably fit within the limits of the physical memory on a - given system. If the sparse solver work space exceeds physical - memory size, the system will be forced to use virtual memory - (or the system page/swap file). In this case, it is typically - more efficient to run with the ``OUTOFCORE`` memory mode. Assuming - the job fits comfortably within the limits of the machine, - running with the ``INCORE`` memory mode is often ideal for jobs - where repeated solves are performed for a single matrix - factorization. This occurs in a modal or buckling analysis or - when doing multiple load steps in a linear, static analysis. - - For repeated runs with the sparse solver, you may set the - initial sparse solver memory allocation to the amount required - for factorization. This strategy reduces the frequency of - allocation and reallocation in the run to make the ``INCORE`` - option fully effective. If you have a very large memory - system, you may use the Memory_Size argument to increase the - maximum size attempted for in-core runs. + + .. _BCSOPTION_notes: + + This command controls options related to the sparse solver in all analysis types where the sparse + solver can be used. It also controls the Block Lanczos eigensolver in a modal or buckling analysis. + + The sparse solver runs from one large work space (that is, one large memory allocation). The amount + of memory required for the sparse solver is unknown until the matrix structure is preprocessed, + including equation reordering. The amount of memory allocated for the sparse solver is then + dynamically adjusted to supply the solver what it needs to compute the solution. + + If you have a very large memory system, you may want to try selecting the INCORE memory mode for + larger jobs to improve performance. When running the sparse solver on a machine with very slow I/O + performance (for example, slow hard drive speed), you may want to try using the INCORE memory mode + to achieve better performance. However, doing so may require much more memory compared to running in + the OUTOFCORE memory mode. + + Running with the INCORE memory mode is best for jobs which comfortably fit within the limits of the + physical memory on a given system. If the sparse solver work space exceeds physical memory size, the + system will be forced to use virtual memory (or the system page/swap file). In this case, it is + typically more efficient to run with the OUTOFCORE memory mode. Assuming the job fits comfortably + within the limits of the machine, running with the INCORE memory mode is often ideal for jobs where + repeated solves are performed for a single matrix factorization. This occurs in a modal or buckling + analysis or when doing multiple load steps in a linear, static analysis. + + For repeated runs with the sparse solver, you may set the initial sparse solver memory allocation to + the amount required for factorization. This strategy reduces the frequency of allocation and + reallocation in the run to make the INCORE option fully effective. If you have a very large memory + system, you may use the ``Memory_Size`` argument to increase the maximum size attempted for in-core + runs. """ command = f"BCSOPTION,,{memory_option},{memory_size},,,{solve_info}" return self.run(command, **kwargs) - def cgrow(self, action="", par1="", par2="", **kwargs): - """Defines crack-growth information + def cjump( + self, + option: str = "", + input1: str = "", + input2: str = "", + input3: str = "", + input4: str = "", + input5: str = "", + input6: str = "", + input7: str = "", + input8: str = "", + **kwargs, + ): + r"""Initiates a `cycle-jump analysis + `_. - APDL Command: CGROW + Mechanical APDL Command: `CJUMP `_ + + **Command default:** + + .. _CJUMP_default: + + Cycle jump analysis is disabled. Parameters ---------- - action - Specifies the action for defining or manipulating crack-growth - data: + option : str + Option to be applied: + + * ``CRIT`` - Jump criterion. + + * ``INTENT`` - Declaration of cycle jump analysis intent. For an analysis that begins with a + standard solution, specify before the first :ref:`solve` command. + + * ``MINCYC`` - Minimum number of cycles before a jump is allowed (and, if desired, the `empirical + adjustment of minimum intermediate cycles + `_ + ). + + * ``INICYC`` - Minimum number of initial cycles before a jump is allowed. + + * ``MAXJUMP`` - Maximum allowable jump. + + * ``RELTIME`` - Relative time. + + * ``CONTROL`` - Control-variable selection. + + * ``CNMT`` - Material-ID-dependent jump control. + + * ``ADCR`` - Material-ID- and/or control-variable-dependent jump criteria. + + * ``CALC`` - Jump-calculation option. - NEW - Initiate a new set of crack-growth simulation data (default). + * ``PERC`` - Statistical-jump calculation. - CID - Specify the crack-calculation (CINT) ID for energy-release rates to be used in - the fracture criterion calculation. + * ``OUTP`` - Diagnostic information output. - FCOPTION - Specify the fracture criterion for crack-growth/delamination. + input1 : str + Additional input according to the specified Option : This command contains some tables and + extra information which can be inspected in the original documentation pointed above. - CPATH - Specify the element component for crack growth. + input2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - DTIME - Specify the initial time step for crack growth. + input3 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - DTMIN - Specify the minimum time step for crack growth. + input4 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - DTMAX - Specify the maximum time step for crack growth. + input5 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - FCRAT - Fracture criterion ratio (fc). + input6 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - STOP - Stops the analysis when the specified maximum crack extension is reached. + input7 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - METHOD - Define the method of crack propagation. + input8 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. Notes ----- - When ``Action = NEW``, the :meth:`Mapdl.cgrow() ` command initializes a crack-growth - simulation set. Subsequent :meth:`Mapdl.cgrow() ` commands define the parameters - necessary for the simulation. - For multiple cracks, issue multiple :meth:`Mapdl.cgrow("NEW") ` commands (and any - subsequent :meth:`Mapdl.cgrow() ` commands necessary to define the parameters) for each - crack. + .. _CJUMP_notes: - If the analysis is restarted (:meth:`Mapdl.antype("","RESTART") `), the :meth:`Mapdl.cgrow() ` command must - be re-issued. + When ``Option`` = CONTROL, any input of a control variable replaces the default (S). If stress is + also needed in combination with another control variable (or variables), you must specify it + explicitly. - For additional details on this command, see - https://www.mm.bme.hu/~gyebro/files/ans_help_v182/ans_cmd/Hlp_C_CGROW.html + :ref:`cjump` requires a corresponding cyclic loading analysis ( :ref:`cload` ). + For more information, see `Cycle-Jump Analysis + `_ + + This command is also valid in PREP7 ( :ref:`prep7` ). """ - command = f"CGROW,{action},{par1},{par2}" + command = f"CJUMP,{option},{input1},{input2},{input3},{input4},{input5},{input6},{input7},{input8}" return self.run(command, **kwargs) - def cmatrix( - self, - symfac="", - condname="", - numcond="", - grndkey="", - capname="", - **kwargs, - ): - """Performs electrostatic field solutions and calculates the - self and mutual capacitances between multiple conductors.x + def cload(self, option: str = "", input1: str = "", **kwargs): + r"""Initiates a `cyclic-loading analysis + `_. + + Mechanical APDL Command: `CLOAD `_ + + **Command default:** - APDL Command: CMATRIX + .. _CLOAD_default: + + Cyclic load analysis is disabled. Parameters ---------- - symfac - Geometric symmetry factor. Capacitance values are scaled by this - factor which represents the fraction of the total device modeled. - Defaults to 1. - - condname - Alphanumeric prefix identifier used in defining named conductor - components. - - numcond - Total Number of Components. If a ground is modeled, it is to be - included as a component. If a ground is not modeled, but infinite - elements are used to model the far-field ground, a named component - for the far-field ground is not required. - - grndkey - Ground key: + option : str + Option to be applied: + + * ``DEFINE`` - Mark tabular array as a cyclic load table. + + * ``CYCNUM`` - Total number of cycles. - 0 - Ground is one of the components, which is not at infinity. + * ``CYCTIME`` - Cycle time. - 1 - Ground is at infinity (modeled by infinite elements). + * ``TSTEP`` - Enable time-point-range time-stepping. - capname - Array name for computed capacitance matrix. Defaults to CMATRIX. + * ``OUTR`` - Select time points for output. + + input1 : str + Additional input according to the specified Option : This command contains some tables and + extra information which can be inspected in the original documentation pointed above. Notes ----- - To invoke the CMATRIX macro, the exterior nodes of each conductor must - be grouped into individual components using the CM command. Each set - of independent components is assigned a component name with a common - prefix followed by the conductor number. A conductor system with a - ground must also include the ground nodes as a component. The ground - component is numbered last in the component name sequence. - - A ground capacitance matrix relates charge to a voltage vector. A - ground matrix cannot be applied to a circuit modeler. The lumped - capacitance matrix is a combination of lumped "arrangements" of - voltage differences between conductors. Use the lumped capacitance - terms in a circuit modeler to represent capacitances between - conductors. - Enclose all name-strings in single quotes in the CMATRIX command line. + .. _CLOAD_notes: - See the Mechanical APDL Theory Reference and HMAGSOLV in the Low- - Frequency Electromagnetic Analysis Guide for details. + For more information, see `Cyclic-Loading Analysis + `_ - This command does not support multiframe restarts. + This command is also valid in PREP7 ( :ref:`prep7` ). """ - command = f"CMATRIX,{symfac},'{condname}',{numcond},{grndkey},'{capname}'" + command = f"CLOAD,{option},{input1}" return self.run(command, **kwargs) - def cmsopt( + def cmatrix( self, - cmsmeth="", - nmode="", - freqb="", - freqe="", - fbddef="", - fbdval="", - iokey="", + symfac: str = "", + condname: str = "", + numcond: str = "", + grndkey: str = "", + capname: str = "", **kwargs, ): - """Specifies component mode synthesis (CMS) analysis options. + r"""Performs electrostatic field solutions and calculates the self and mutual capacitances between + multiple conductors. - APDL Command: CMSOPT + Mechanical APDL Command: `CMATRIX `_ Parameters ---------- - cmsmeth - The component mode synthesis method to use. This value is required. - - FIX - Fixed-interface method. - - FREE - Free-interface method. - - RFFB - Residual-flexible free-interface method. - - nmode - The number of normal modes extracted and used in the superelement - generation. This value is required; the minimum is 1. - - freqb - Beginning, or lower end, of frequency range of interest. This value - is optional. - - freqe - Ending, or upper end, of frequency range of interest. This value is - optional. - - fbddef - In a free-interface (CMSMETH = FREE) or residual-flexible free- - interface (CMSMETH = RFFB) CMS analysis, the method to use for - defining free body modes: - - FNUM - The number (FDBVAL) of rigid body modes in the calculation. - - FTOL - Employ a specified tolerance (FDBVAL) to determine rigid body modes in the - calculation. - - FAUTO - Automatically determine rigid body modes in the calculation. This method is the - default. - - RIGID - If no rigid body modes exist, define your own via the RIGID command. - - fbdval - In a free-interface CMS analysis (CMSMETH = FREE), the number of - rigid body modes if FBDDEF = fnum (where the value is an integer - from 0 through 6), or the tolerance to employ if FBDDEF = ftol - (where the value is a positive real number representing rad/sec). - This value is required only when FBDDEF = fnum or FBDDEF = ftol; - otherwise, any specified value is ignored. - - iokey - Output key to control writing of the transformation matrix to the - .TCMS file (FIX or FREE methods) or body properties to the .EXB - file (FIX method). - - TCMS - Write the transformation matrix of the nodal component defined by the OUTPR - command to a .TCMS file. Refer to TCMS File Format in the - Programmer's Reference for more information on the this - file. - - EXB - Write a body property input file (.EXB file) containing the condensed - substructure matrices and other body properties for use with - AVL EXCITE. Refer to ANSYS Interface to AVL EXCITE in the - Substructuring Analysis Guide for more information. + symfac : str + Geometric symmetry factor. Capacitance values are scaled by this factor which represents the + fraction of the total device modeled. Defaults to 1. + + condname : str + Alpha-numeric prefix identifier used in defining named conductor components. + + numcond : str + Total Number of Components. If a ground is modeled, it is to be included as a component. If a + ground is not modeled, but infinite elements are used to model the far-field ground, a named + component for the far-field ground is not required. + + grndkey : int or str + Ground key: + + * ``0`` - Ground is one of the components, which is not at infinity. + + * ``1`` - Ground is at infinity (modeled by infinite elements). + + capname : str + Array name for computed capacitance matrix. Defaults to :ref:`cmatrix`. Notes ----- - CMS employs the Block Lanczos eigensolution method in the generation - pass. - CMS supports damping matrix reduction when a damping matrix exists. Set - the matrix generation key to 3 (SEOPT,Sename,SEMATR) to generate and - then reduce stiffness, mass, and damping matrices. + .. _CMATRIX_notes: + + To invoke the :ref:`cmatrix` macro, the exterior nodes of each conductor must be grouped into + individual components using the :ref:`cm` command. Each set of independent components is assigned a + component name with a common prefix followed by the conductor number. A conductor system with a + ground must also include the ground nodes as a component. The ground component is numbered last in + the component name sequence. - CMS does not support the SEOPT,,,,,RESOLVE command. Instead, ANSYS sets - the expansion method for the expansion pass (EXPMTH) to BACKSUB. + A ground capacitance matrix relates charge to a voltage vector. A ground matrix cannot be applied to + a circuit modeler. The lumped capacitance matrix is a combination of lumped "arrangements" of + voltage differences between conductors. Use the lumped capacitance terms in a circuit modeler to + represent capacitances between conductors. - For more information about performing a CMS analysis, see Component - Mode Synthesis in the Substructuring Analysis Guide. + Enclose all name-strings in single quotes in the :ref:`cmatrix` command line. - If IOKEY = TCMS is used to output the transformation matrix, then only - ITEM = NSOL is valid in the OUTPR command. In the interactive - sessions, the transformation matrix will not be output if the model has - more than 10 elements. + See the `Mechanical APDL Theory Reference + `_ for details. - This command is also valid in /PREP7. + This command does not support multiframe restarts. """ - command = f"CMSOPT,{cmsmeth},{nmode},{freqb},{freqe},{fbddef},{fbdval},{iokey}" + command = f"CMATRIX,{symfac},'{condname}',{numcond},{grndkey},'{capname}'" return self.run(command, **kwargs) - def cncheck( + def cmsopt( self, - option="", - rid1="", - rid2="", - rinc="", - intertype="", - trlevel="", - cgap="", - cpen="", - ioff="", + cmsmeth: str = "", + nmode: str = "", + freqb: str = "", + freqe: str = "", + fbddef: str = "", + fbdval: str = "", + iokey: str = "", + elcalc: str = "", + eigmeth: str = "", + nstartvn: str = "", **kwargs, ): - """Provides and/or adjusts the initial status of contact pairs. + r"""Specifies component mode synthesis (CMS) analysis options. - APDL Command: CNCHECK + Mechanical APDL Command: `CMSOPT `_ - Parameters - ---------- - option - Option to be performed: + **Command default:** - * ``"DETAIL"`` : List all contact pair properties (default). + .. _CMSOPT_default: - * ``"SUMMARY"`` : List only the open/closed status for each - contact pair. + Issuing the :ref:`cmsopt` command with no arguments is invalid. You must specify at least the CMS + method ( ``Cmsmeth`` ) and the number of modes ( ``NMODE`` ). In a free-interface ( ``Cmsmeth`` = + FREE) or residual-flexible free-interface ( ``Cmsmeth`` = RFFB) CMS analysis, the default method for + determining rigid body modes is FAUTO (automatic). + + Parameters + ---------- + cmsmeth : str + The component mode synthesis `method `_ to use. This value is required. - * ``"POST"`` : Execute a partial solution to write the initial - contact configuration to the Jobname.RCN file. + * ``FIX`` - Fixed-interface method. - * ``"ADJUST"`` : Physically move contact nodes to the target - in order to close a gap or reduce penetration. The initial - adjustment is converted to structural displacement values - (UX, UY, UZ) and stored in the Jobname.RCN file. + * ``FREE`` - Free-interface method. - * ``"MORPH"`` : Physically move contact nodes to the target in - order to close a gap or reduce penetration, and also morph - the underlying solid mesh. The initial adjustment of contact - nodes and repositioning of solid element nodes due to mesh - morphing are converted to structural displacement values - (UX, UY, UZ) and stored in the Jobname.RCN file. + * ``RFFB`` - Residual-flexible free-interface method. - * ``"RESET"`` : Reset target element and contact element key - options and real constants to their default values. This - option is not valid for general contact. + nmode : str + The number of normal modes extracted and used in the superelement generation. This value is + required; the minimum is 1. - * ``"AUTO"`` : Automatically sets certain real constants and - key options to recommended values or settings in order to - achieve better convergence based on overall contact pair - behaviors. This option is not valid for general contact. + freqb : str + Beginning, or lower end, of frequency range of interest. This value is optional. - * ``"TRIM"`` : Trim contact pair (remove certain contact and - target elements). + The program always sets this value to zero if the residual-flexible free-interface method ( + ``Cmsmeth`` = RFFB) or the free-interface method ( ``Cmsmeth`` = FREE) is specified via + :ref:`resvec`. - * ``"UNSE"`` : Unselect certain contact and target elements. + freqe : str + Ending, or upper end, of frequency range of interest. This value is optional. - rid1, rid2, rinc - For pair-based contact, the range of real constant pair IDs - for which Option will be performed. If RID2 is not specified, - it defaults to RID1. If no value is specified, all contact - pairs in the selected set of elements are considered. + fbddef : str + In a free-interface ( ``Cmsmeth`` = FREE) or residual-flexible free-interface ( ``Cmsmeth`` = RFFB) CMS analysis, the method to use for defining free body modes: - For general contact (InterType = GCN), RID1 and RID2 are - section IDs associated with general contact surfaces instead - of real constant IDs. If RINC = 0, the Option is performed - between the two sections, RID1 and RID2. If RINC > 0, the - Option is performed among all specified sections (RID1 to RID2 - with increment of RINC). + * ``FNUM`` - The number ( ``FDBVAL`` ) of rigid body modes in the calculation. - intertype - The type of contact interface (pair-based versus general - contact) to be considered; or the type of contact pair to be - trimmed/unselected/auto-set. + * ``FTOL`` - Employ a specified tolerance ( ``FDBVAL`` ) to determine rigid body modes in the + calculation. - The following labels specify the type of contact interface: + * ``FAUTO`` - Automatically determine rigid body modes in the calculation. This method is the + default. - * ``""`` : (blank) Include all contact definitions (pair-based - and general contact). + * ``RIGID`` - If no rigid body modes exist, define your own via the :ref:`rigid` command. - * ``"GCN"`` : Include general contact definitions only (not valid when Option = RESET or AUTO). + fbdval : str + In a free-interface CMS analysis ( ``Cmsmeth`` = FREE), the number of rigid body modes if + ``Fbddef`` = FNUM (where the value is an integer from 0 through 6), or the tolerance to employ + if ``Fbddef`` = FTOL (where the value is a positive real number representing rad/sec). This + value is required only when ``Fbddef`` = FNUM or ``Fbddef`` = FTOL; otherwise, any specified + value is ignored. - The following labels specify the type of contact pairs to be - trimmed/unselected/auto-set (used only when Option = TRIM, - UNSE, or AUTO, and only for pair-based contact definitions): + iokey : str + Output key to control writing of the complete transformation matrix on the :file:`.cms` file to the + :file:`.tcms` file (FIX or FREE methods) or body properties to the :file:`.EXB` file (FIX method). - * ``"ANY"`` : All types (default). + * ``CMS`` - Write the complete transformation matrix of the nodal component on the :file:`.cms` + file. For more information, see. - * ``"MPC"`` : MPC-based contact pairs (KEYOPT(2) = 2). + * ``TCMS`` - Write the transformation matrix of the nodal component defined via :ref:`outpr` to a + :file:`.tcms` file. For more information, see. - * ``"BOND"`` : Bonded contact pairs (KEYOPT(12) = 3, 5, 6). + * ``EXB`` - Write a body property input file ( :file:`.EXB` file) containing the condensed + substructure matrices and other body properties for use with AVL EXCITE. For more information, see + `Ansys Interface to AVL EXCITE + `_ - * ``"NOSP"`` : No separation contact pairs (KEYOPT(12) = 2, 4). + elcalc : str + Element calculation key: - * ``"INAC"`` : Inactive contact pairs (symmetric contact pairs for MPC contact or KEYOPT(8) = 2). + * ``NO`` - Do not calculate element results (default). - * ``"TRlevel"`` : mming level (used only when Option = TRIM, UNSE, or MORPH): + * ``YES`` - Calculate element results and write them to the :file:`.cms` file for the expansion + pass. - * ``"(blank)"`` : Normal trimming (default): remove/unselect contact and target elements which are in far-field. + eigmeth : str + Mode extraction method to be used for the symmetric eigenvalue problem during the `generation pass + `_ + : - * ``"AGGRE"`` : Aggressive trimming: remove/unselect contact and target elements which are in far-field, and certain elements in near-field. + * ``LANB`` - Block Lanczos algorithm (default). - cgap - They are only valid when Option = ADJUST or MORPH. Control - parameter for opening gap. Close the opening gap if the - absolute value of the gap is smaller than the CGAP value. CGAP - defaults to ``0.25*PINB`` (where PINB is the pinball radius) for - bonded and no-separation contact; otherwise it defaults to the - value of real constant ICONT. + * ``SUBS`` - Subspace algorithm. - CPEN - They are only valid when Option = ADJUST or MORPH. Control - parameter for initial penetration. Close the initial - penetration if the absolute value of the penetration is - smaller than the CPEN value. CPEN defaults to ``0.25*PINB`` (where - PINB is the pinball radius) for any type of interface behavior - (either bonded or standard contact). + * ``SNODE`` - Supernode algorithm. - IOFF - They are only valid when Option = ADJUST or MORPH. Control - parameter for initial adjustment. Input a positive value to - adjust the contact nodes towards the target surface with a - constant interference distance equal to IOFF. Input a negative - value to adjust the contact node towards the target surface - with a uniform gap distance equal to the absolute value of - IOFF. + nstartvn : str + Node number to be assigned to the first virtual node created to store the generalized + coordinates. See :ref:`CMSOPT_notes` for more information. Notes ----- - The CNCHECK command provides information for surface-to-surface, - node-to-surface, and line-to-line contact pairs (element types - TARGE169, TARGE170, CONTA171, CONTA172, CONTA173, CONTA174, - CONTA175, CONTA176, CONTA177). All contact and target elements of - interest, along with the solid elements and nodes attached to - them, must be selected for the command to function properly. For - performance reasons, the program uses a subset of nodes and - elements based on the specified contact regions (RID1, RID2, RINC) - when executing the CNCHECK command. - - For additional details, see the notes section at: - https://www.mm.bme.hu/~gyebro/files/ans_help_v182/ans_cmd/Hlp_C_CNCHECK.html + .. _CMSOPT_notes: + + CMS supports damping matrix reduction when a damping matrix exists. Set the matrix generation key to + 3 ( :ref:`seopt`, ``Sename``, ``SEMATR`` ) to generate and then reduce stiffness, mass, and damping + matrices. + + CMS does not support the :ref:`seopt`,,,,,RESOLVE command. Instead, the program sets the expansion + method for the expansion pass ( ``EXPMTH`` ) to BACKSUB. + + By default, the static constraint modes are not written to the :file:`.cms` file for the fixed- + interface and free-interface methods. Issue ``IOkey`` = CMS to write them. + + If ``IOkey`` = TCMS, the transformation matrix is printed out and written to the :file:`.tcms` file + when the :ref:`outpr` command is issued with ``ITEM`` = NSOL and ``FREQ`` not equal to NONE. In + addition, the transformation matrix is printed out when ``SEPR`` is equal to 1 or 2 on :ref:`seopt`. + In interactive sessions, the transformation matrix is not output if the model has more than 10 + elements. + + For information about the component modes stored in the :file:`.cms` or :file:`.tcms` file, refer to + `Component Modes Storage + `_ + + If ``Elcalc`` = YES, the element results of the component modes included in the transformation + matrix of the CMS method are calculated and written to the :file:`.cms` file. This can significantly + reduce the computation time of the. For limitations and available element results, see. + + Select a ``nStartVN`` value to offset the virtual node numbers from the other node numbers used in + the model; otherwise, the program selects ``nStartVN`` to fulfill that condition. In the case of + multiple superelements, if ``nStartVN`` is defined during each generation pass, then in the use + pass, the virtual nodes of all imported superelements are gathered and renumbered from the + ``nStartVN`` value specified for the first encountered superelement (first :ref:`se` command). + ``nStartVN`` can also be defined in the use pass via :ref:`se`. (If ``nStartVN`` is defined by both + the :ref:`cmsopt` and :ref:`se` commands, the larger number prevails.) + + For more information, see `Component Mode Synthesis + `_ + + This command is also valid in :ref:`prep7`. + + .. _CMSOPT_prodres: + + Ansys Mechanical Enterprise PrepPost Only :ref:`cmsopt`,FIX,,,,,,EXB is supported. """ - command = f"CNCHECK,{option},{rid1},{rid2},{rinc},{intertype},{trlevel},{cgap},{cpen},{ioff}" + command = f"CMSOPT,{cmsmeth},{nmode},{freqb},{freqe},{fbddef},{fbdval},{iokey},,,{elcalc},,{eigmeth},{nstartvn}" return self.run(command, **kwargs) - def cnkmod(self, itype="", knum="", value="", **kwargs): - """Modifies contact element key options. + def cnkmod(self, itype: str = "", knum: str = "", value: str = "", **kwargs): + r"""Modifies contact element key options. - APDL Command: CNKMOD + Mechanical APDL Command: `CNKMOD `_ Parameters ---------- - itype - Contact element type number as defined on the ET command. + itype : str + Contact element type number as defined on the :ref:`et` command. - knum - Number of the KEYOPT to be modified (KEYOPT(KNUM)). + knum : str + Number of the KEYOPT to be modified (KEYOPT( ``KNUM`` )). - value + value : str Value to be assigned to the KEYOPT. Notes ----- - The CNKMOD command has the same syntax as the KEYOPT command. However, - it is valid only in the SOLUTION processor. This command is intended - only for use in a linear perturbation analysis, and can only be used to - modify certain contact element KEYOPT values as described below. - - Modifying KEYOPT(12) - - One use for this command is to modify contact interface behavior - between load steps in a linear perturbation analysis; it allows the - user to control the contact status locally per contact pair. For this - application, this command is limited to changing the contact interface - behavior key option: KEYOPT(12) of CONTA171, CONTA172, CONTA173, - CONTA174, CONTA175, CONTA176, and CONTA177; and KEYOPT(10) of CONTA178. - - When used for this purpose, the command adjusts the contact status from - the linear perturbation base analysis (at the point of restart) as - described in the table below. Note that CNKMOD allows you to take - points in the base analysis that are near contact (within the pinball - region) and modify them to be treated as "in contact" in the - perturbation analysis; see the "1 - near-field" row with KEYOPT(12) - values set to 4 or 5. CNKMOD also allows you to take points that are - sliding in the base analysis and treat them as sticking in the - perturbation analysis, irrespective of the MU value; see the "2 - - sliding" row with KEYOPT(12) values set to 1,3, 5, or 6. - - Table: 128:: : Adjusted Contact Status with CNKMOD is Issued - - (if outside of the adjusted pinball region) - - (if inside of the adjusted pinball region) - - (if outside of the adjusted pinball region) - - (if inside of the adjusted pinball region) - - If an open gap exists at the end of the previous load step and the - contact status is adjusted as sliding or sticking due to a "bonded" or - "no separation" contact behavior definition, then the program will - treat it as near-field contact when executing CNKMOD in the subsequent - load steps. - - In the linear perturbation analysis procedure, contact status can also - be controlled or modified by the PERTURB command. The contact status - always follows local controls defined by the CNKMOD command first, and - is then adjusted by the global sticking or bonded setting (ContKey = - STICKING or BONDED) on the PERTURB command (see the PERTURB command for - details). - - Modifying KEYOPT(3) - - Another use for this command is to change the units of normal contact - stiffness (contact element real constant FKN) in a linear perturbation - modal analysis that is used to model brake squeal. For contact elements - CONTA171, CONTA172, CONTA173, and CONTA174, KEYOPT(3) controls the - units of normal contact stiffness. You can issue the command - CNKMOD,ITYPE,3,1 during the first phase of the linear perturbation - analysis in order to change the units of normal contact stiffness from - FORCE/LENGTH3 (in the base analysis) to FORCE/LENGTH. Note that - KEYOPT(3) = 1 is valid only when a penalty-based algorithm is used - (KEYOPT(2) = 0 or 1) and the absolute normal contact stiffness value is - explicitly specified (that is, a negative value input for real constant - FKN). + + .. _CNKMOD_notes: + + The :ref:`cnkmod` command has the same syntax as the :ref:`keyopt` command. However, it is valid + only in the SOLUTION processor. The command can be used to modify certain contact element KEYOPT + values between load steps in any analysis, including restarts and `linear perturbation + `_ analyses, as + shown in the table below. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + In a `multiframe restart + `_, + :ref:`cnkmod` must be issued again during each subsequent restart run. + + **Modifying KEYOPT(12)** + + A common use for the :ref:`cnkmod` command is to modify contact interface behavior between load + steps in a restart analysis, a linear perturbation analysis, or other types of analyses. This + enables you to control the contact status locally per contact pair. The key options that control + contact interface behavior are: KEYOPT(12) of ``CONTA172``, ``CONTA174``, ``CONTA175``, and + ``CONTA177`` ; and KEYOPT(10) of ``CONTA178``. + + You can change KEYOPT(12) to any value. For example, you can change from standard contact to bonded + contact or vice-versa. If an open gap exists at the end of the previous load step and the contact + status is adjusted to sliding or sticking due to a bonded or no-separation contact behavior + definition, the program considers it as near-field contact when executing :ref:`cnkmod` in the + subsequent load steps. + + In a `linear perturbation analysis + `_, the + :ref:`cnkmod` command adjusts the contact status from the linear perturbation base analysis (at the + point of restart) as described in the table below. It enables you to take points in the base + analysis that are near contact (within the pinball region) and modify them to be treated as in- + contact in the perturbation analysis (see the "1 - near-field" row with KEYOPT(12) values set to 4 + or 5). You can also take points that are sliding in the base analysis and treat them as sticking in + the perturbation analysis, irrespective of the MU value (see the "2 - sliding" row with KEYOPT(12) + values set to 1,3, 5, or 6). + + Contact Status Adjusted in Linear Perturbation Analysis via CNKMOD + ****************************************************************** + + .. flat-table:: + + * - :rspan:`1` **Contact Status from the Base Analysis Solution at the Restart Point** + - *\*CNKMOD,** ``ITYPE`` ,12, ``Value`` + * - KEYOPT(12) Value + - Adjusted Contact Status + * - 0 - far-field + - any + - 0 - far-field + * - :rspan:`4` 1 - near-field + - 0, 1, 2, 3, 6 + - 1 - near-field + * - :rspan:`1` 4 + - 1 - near-field (if outside of the adjusted pinball region) + * - 2 - sliding (if inside of the adjusted pinball region) + * - :rspan:`1` 5 + - 1 - near-field (if outside of the adjusted pinball region) + * - 3 - sticking (if inside of the adjusted pinball region) + * - :rspan:`1` 2 - sliding + - 0, 2, 4 + - 2 - sliding + * - 1, 3, 5, 6 + - 3 - sticking + * - 3 - sticking + - any + - 3 - sticking + + If an open gap exists at the end of the previous load step and the contact status is adjusted as + sliding or sticking due to a bonded or no-separation contact behavior definition, the program + considers it a near-field contact when executing :ref:`cnkmod` in the subsequent load steps. + + In the linear perturbation analysis procedure, contact status can also be controlled or modified via + the :ref:`perturb` command. The contact status always follows local controls defined by the + :ref:`cnkmod` command first, and is then adjusted by the global sticking or bonded setting ( + ``ContKey`` = STICKING or BONDED) on the :ref:`perturb` command. + + **Modifying KEYOPT(3)** + + Another use for the :ref:`cnkmod` command is to change the units of normal contact stiffness + (contact element real constant FKN) in a `linear perturbation modal analysis + `_ that is used + to model `brake squeal + `_. + For contact elements ``CONTA172`` and ``CONTA174``, KEYOPT(3) controls the units of normal contact + stiffness. You can issue the command :ref:`cnkmod`, ``ITYPE``,3,1 during the first phase of the + linear perturbation analysis in order to change the units of normal contact stiffness from + FORCE/LENGTH :sup:`3` (in the base analysis) to FORCE/LENGTH. Note that KEYOPT(3) = 1 is valid only + when a penalty-based algorithm is used (KEYOPT(2) = 0 or 1) and the absolute normal contact + stiffness value is explicitly specified (that is, a negative value input for real constant FKN). + + **Modifying KEYOPT(15)** + + KEYOPT(15) controls the effect of contact stabilization damping for contact elements ``CONTA172``, + ``CONTA174``, ``CONTA175``, and ``CONTA177``. You can use :ref:`cnkmod` to activate or deactivate + the contact stabilization damping between load steps. For example, the command :ref:`cnkmod`, + ``ITYPE``,15,1 deactivates the contact stabilization damping. """ command = f"CNKMOD,{itype},{knum},{value}" return self.run(command, **kwargs) - def cntr(self, option="", key="", **kwargs): - """Redirects contact pair output quantities to a text file. + def cntr(self, option: str = "", key: str = "", **kwargs): + r"""Redirects contact pair output quantities to a text file. + + Mechanical APDL Command: `CNTR `_ + + **Command default:** - APDL Command: CNTR + .. _CNTR_default: + + Contact pair output quantities are written to the output file ( :file:`Jobname.OUT` ) or to the + screen, as specified by the :ref:`output` command. Parameters ---------- - option + option : str Output option: - OUT - Contact output control. + * ``OUT`` - Contact output control. - key + key : str Control key: - NO - Write contact information to the output file or to the screen (default). + * ``NO`` - Write contact information to the output file or to the screen (default). - YES - Write contact information to the Jobname.CNM file. + * ``YES`` - Write contact information to the :file:`Jobname.CNM` file. Notes ----- - Issue the command CNTR,OUT,YES to redirect contact pair output - quantities to the Jobname.CNM file. - To ensure that the contact information is written to Jobname.CNM, - reissue CNTR,OUT,YES each time you reenter the solution processor - (/SOLU). + .. _CNTR_notes: + + Issue the command :ref:`cntr`,OUT,YES to redirect contact pair output quantities to the + :file:`Jobname.CNM` file. + + To ensure that the contact information is written to :file:`Jobname.CNM`, reissue + :ref:`cntr`,OUT,YES each time you reenter the solution processor ( :ref:`slashsolu` ). """ command = f"CNTR,{option},{key}" return self.run(command, **kwargs) - def cutcontrol(self, lab="", value="", option="", **kwargs): - """Controls time-step cutback during a nonlinear solution. + def cutcontrol(self, lab: str = "", value: str = "", option: str = "", **kwargs): + r"""Controls time-step cutback during a nonlinear solution. - APDL Command: CUTCONTROL + Mechanical APDL Command: `CUTCONTROL `_ Parameters ---------- - lab - Specifies the criteria for causing a cutback. Valid labels are: - - PLSLIMIT - Maximum equivalent plastic strain allowed within a time-step (substep). If the - calculated value exceeds the VALUE, the program - performs a cutback (bisection). VALUE defaults to 0.15 - (15%). - - CRPLIMIT - Set values for calculating the maximum equivalent creep ratio allowed within a - time step. If the calculated maximum creep ratio - exceeds the defined creep ratio limit, the program - performs a cutback. - - DSPLIMIT - Maximum incremental displacement within the solution field in a time step - (substep). If the maximum calculated value exceeds - VALUE, the program performs a cutback (bisection). - VALUE defaults to 1.0 x 107. - - NPOINT - Number of points in a cycle for a second order dynamic equation, used to - control automatic time stepping. If the number of - solution points per cycle is less than VALUE, the program - performs a cutback in time step size. VALUE defaults to - 13 for linear analysis, 5 for nonlinear analysis. A - larger number of points yields a more accurate solution - but also increases the solution run time. - - This option works well for linear problems. For nonlinear analyses, other - factors such as contact status changes and solution convergence rate can - overwrite NPOINT. See Automatic Time Stepping in the Mechanical APDL - Theory Reference for more information on automatic time stepping. - - NOITERPREDICT - - If VALUE is 0 (default), an internal auto time step scheme will predict - the number of iterations for nonlinear convergence and perform a cutback - earlier than the number of iterations specified by the NEQIT command. - This is the recommended option. - - If VALUE is 1, the solution will iterate (if nonconvergent) to NEQIT - number of iterations before a cutback is invoked. - It is sometimes useful for poorly-convergent problems, but rarely needed in general. - - Bisection is also controlled by contact status change, plasticity or creep - strain limit, and other factors. If any of these - factors occur, bisection will still take place, - regardless of the NOITERPREDICT setting. - - CUTBACKFACTOR - Changes the cutback value for bisection. Default is 0.5. VALUE must be greater - than 0.0 and less than 1.0. This option is active - only if AUTOTS,ON is set. - - value - Numeric value for the specified cutback criterion. For Lab = - CRPLIMIT, VALUE is the creep criteria for the creep ratio limit. - - option - Type of creep analysis. Valid for Lab = CRPLIMIT only. - - IMPRATIO - Set the maximum creep ratio value for implicit creep. The default is 0.0 (i.e., - no creep limit control) and any positive value is - valid. (See Implicit Creep Procedure in the Structural - Analysis Guide for information on how to define - implicit creep.) - - EXPRATIO - Set the maximum creep ratio value for explicit creep. The default value is 0.1 - and any positive value up to 0.25 is allowed. (See - Explicit Creep Procedure in the Structural Analysis - Guide for information on how to define explicit - creep.) - - STSLIMIT - Stress threshold for calculating the creep ratio. For integration points with - effective stress below this threshold, the creep ratio - does not cause cutback. The default value is 0.0 and - any positive value is valid. - - STNLIMIT - Elastic strain threshold for calculating the creep ratio. For integration - points with effective elastic strain below this - threshold, the creep ratio does not cause cutback. The - default value is 0.0 and any positive value is valid. + lab : str + Specifies the criteria for causing a cutback. Valid labels are: + + * ``ALIMIT`` - Set the maximum edge-flux degree-of-freedom increment allowed within a time step. If + the absolute value of the calculated increment within a time step exceeds ``VALUE``, the program + performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This cutback trigger + criterion is part of the :ref:`physics limit set. ` + + * ``CONCLIMIT`` - Set the maximum concentration degree-of-freedom increment allowed within a time + step. If the absolute value of the calculated increment within a time step exceeds ``VALUE``, the + program performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This cutback + trigger criterion is part of the :ref:`physics limit set. ` + + * ``CRPLIMIT`` - Set values for calculating the maximum equivalent creep ratio allowed within a time + step. If the calculated maximum creep ratio exceeds the defined creep-ratio limit, the program + performs a cutback. For the first substep or the rebalance substeps after remeshing in `nonlinear + mesh adaptivity + `_ or `rezoning + `_, however, + the user-defined maximum plastic-strain limit is ignored. + + * ``CUTBACKFACTOR`` - Key to set the cutback factor, a multiplier for reducing the time step + interval to the fraction specified in ``VALUE``, where 0 < ``VALUE`` < 1 (default is 0.5 if + ``VALUE`` is not specified.) The option to change the cutback factor is valid only when automatic + time stepping is on ( :ref:`autots`,ON), which is the default. + + * ``DMGLIMIT`` - For damage models (such as `generalized damage and anisotropic damage + `_ + ), the maximum allowable damage increment in a time step. If the calculated value exceeds ``VALUE``, + the program performs a cutback (bisection). If ``VALUE`` is unspecified, the program does not check + the allowable damage increment. + + * ``DPPLMT`` - Set the maximum pore-pressure increment allowed within a time step. If the calculated + maximum increment exceeds the specified limit, the program performs a cutback. This option has no + default and is valid for coupled `structural-pore-fluid-diffusion + `_ + analysis only. + + * ``DSPLIMIT`` - Set the maximum degree-of-freedom increment allowed within a time step. Considering + all degrees of freedom at every node, if the absolute value of the maximum incremental degree-of- + freedom solution within in a time step exceeds ``VALUE``, the program performs a cutback. If not + specified, default ``VALUE`` = 1.0 x 10 :sup:`7`.This cutback trigger criterion is the sole member + of the :ref:`DSPLIMIT set. ` + + * ``EMFLIMIT`` - Set the maximum electromotive force degree-of-freedom increment allowed within a + time step. If the absolute value of the calculated increment within a time step exceeds ``VALUE``, + the program performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This + cutback trigger criterion is part of the :ref:`physics limit set. ` + + * ``MAGLIMIT`` - Set the maximum scalar magnetic potential degree-of-freedom increment allowed + within a time step. If the absolute value of the calculated increment within a time step exceeds + ``VALUE``, the program performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. + This cutback trigger criterion is part of the :ref:`physics limit set. ` + + * ``MDMG`` - For regularized `microplane + `_ + damage models, the maximum allowable microplane homogenized damage increment in a time step. If the + calculated value exceeds ``VALUE``, the program performs a cutback (bisection). If ``VALUE`` is + unspecified, the program does not check the allowable microplane homogenized damage increment. + + * ``PLSLIMIT`` - Maximum equivalent plastic strain allowed within a time-step (substep). If the + calculated value exceeds ``VALUE``, the program performs a cutback (bisection). Default: ``VALUE`` = + 0.15 (15 percent) + + If :ref:`cutcontrol` with ``Lab`` = PLSLIMIT is not issued, the minimum time step specified is + reached, and the maximum plastic limit calculated from the solution exceeds 15 percent, the program + generates a warning and continues the Newton iterations. + + If :ref:`cutcontrol` with ``Lab`` = PLSLIMIT is issued, the minimum time step specified is reached, + and the maximum plastic limit calculated exceeds the specified limit, the program generates an error + and stops the Newton iterations. For the first substep or the rebalance substeps after remeshing in + `nonlinear mesh adaptivity + `_ or `rezoning + `_, however, + the user-defined maximum plastic-strain limit is ignored. + + * ``PRESLIMIT`` - Set the maximum pressure degree-of-freedom increment allowed within a time step. + If the absolute value of the calculated increment within a time step exceeds ``VALUE``, the program + performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This cutback trigger + criterion is part of the :ref:`physics limit set. ` + + * ``ROTLIMIT`` - Set the maximum rotation degree-of-freedom increment allowed within a time step. If + the absolute value of the calculated increment within a time step exceeds ``VALUE``, the program + performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`7`. This cutback trigger + criterion is part of the :ref:`physics limit set. ` + + * ``TEMPLIMIT`` - Set the maximum temperature degree-of-freedom increment allowed within a time + step. If the absolute value of the calculated increment within a time step exceeds ``VALUE``, the + program performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This cutback + trigger criterion is part of the :ref:`physics limit set and is also valid for + ` `coupled structural-pore-fluid-diffusion-thermal analysis + `_. + + * ``ULIMIT`` - Set the maximum translation degree-of-freedom increment allowed within a time step. + If the absolute value of the calculated increment within a time step exceeds ``VALUE``, the program + performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`7`. This cutback trigger + criterion is part of the :ref:`physics limit set. ` + + * ``VOLTLIMIT`` - Set the maximum volt degree-of-freedom increment allowed within a time step. If + the absolute value of the calculated increment within a time step exceeds ``VALUE``, the program + performs a cutback. If not specified, default ``VALUE`` = 1.0 x 10 :sup:`25`. This cutback trigger + criterion is part of the :ref:`physics limit set. ` + + * ``VSLIMIT`` - For `viscoelastic + `_ + materials, the `maximum equivalent viscous strain increment + `_ + allowed within a time step. If the calculated value exceeds ``VALUE`` (default = 0.01), the program + performs a cutback (bisection). If ``VALUE`` = 0, the program does not check the equivalent viscous + strain increment. + + * ``Other Valid Labels:`` - + + * ``NOITERPREDICT`` - If ``VALUE`` = 0 (default), the program predicts the number of iterations for + nonlinear convergence and performs a cutback earlier than the number of iterations specified ( + :ref:`neqit` ). This is the recommended option. + + If ``VALUE`` = 1, the solution iterates (if nonconvergent) to :ref:`neqit` number of iterations + before a cutback is invoked. It is sometimes useful for poorly-convergent problems, but rarely + needed in general. + + Bisection is also controlled by contact status change, plasticity or creep strain limit, and other + factors. If any of these factors occur, bisection still occurs, regardless of the NOITERPREDICT + setting. + + * ``NPOINT`` - Number of points in a cycle for a second order dynamic equation, used to control + automatic time- stepping. If the number of solution points per cycle is less than ``VALUE``, the + program performs a cutback in time step size. Default: ``VALUE`` = 13 (linear analysis) or 5 + (nonlinear analysis). A larger number of points yields a more accurate solution but also increases + the solution run time. + + This option works well for linear problems. For nonlinear analyses, other factors such as contact + status changes and solution convergence rate can overwrite NPOINT. (See `Automatic Time-Stepping + `_ + + value : str + Numeric value for the specified cutback criterion. For ``Lab`` = CRPLIMIT only, ``VALUE`` is the + creep criteria for the creep ratio limit. + + option : str + Type of creep analysis. Valid for ``Lab`` = CRPLIMIT only. + + * ``IMPRATIO`` - Set the `maximum creep ratio + `_ + value for implicit creep. Default = 0.0 (no creep limit control). Any positive value is valid. + + * ``STSLIMIT`` - Stress threshold for calculating the creep ratio. For integration points with + effective stress below this threshold, the creep ratio does not cause cutback. Default = 0.0. Any + positive value is valid. + + * ``STNLIMIT`` - Elastic strain threshold for calculating the creep ratio. For integration points + with effective elastic strain below this threshold, the creep ratio does not cause cutback. Default + = 0.0. Any positive value is valid. Notes ----- - A cutback is a method for automatically reducing the step size when - either the solution error is too large or the solution encounters - convergence difficulties during a nonlinear analysis. - - Should a convergence failure occur, the program reduces the time step - interval to a fraction of its previous size and automatically continues - the solution from the last successfully converged time step. If the - reduced time step again fails to converge, the program again reduces - the time step size and proceeds with the solution. This process - continues until convergence is achieved or the minimum specified time - step value is reached. - - For creep analysis, the cutback procedure is similar; the process - continues until the minimum specified time step size is reached. - However, if the creep ratio limit is exceeded, the program issues a - warning but continues the substep until the analysis is complete. In - this case, convergence is achieved but the creep ratio criteria is not - satisfied. - - The CRPLIM command is functionally equivalent to Lab = CRPLIMIT with - options IMPRATIO and EXPRATIO + A cutback is a method for automatically reducing the step size when either the solution error is too + large or the solution encounters convergence difficulties during a nonlinear analysis. + + If a convergence failure occurs, the program reduces the time step interval to a fraction of its + previous size and automatically continues the solution from the last successfully converged time + step. If the reduced time step again fails to converge, the program again reduces the time step size + and proceeds with the solution. This process continues until convergence is achieved or the minimum + specified time step value is reached. + + A cutback occurs when a trigger criteria is encountered. The magnitude of the time-step reduction is + determined by the cutback factor. Both the trigger and the cutback factor can be specified via + :ref:`cutcontrol` : + + * The trigger criteria can be specified for individual physics as detailed in :ref:`CUTCONTROL_Lab` + ``Lab`` descriptions above. + + * The cutback factor is 0.5 by default, and can be specified via the :ref:`CUTBACKFACTOR label + described above. ` + + :ref:`cutcontrol` can be issued multiple times. + + .. _CUTCONTROL_DSPLIMITSet: + + DSPLIMIT Set + ^^^^^^^^^^^^ + + DSPLIMIT is the sole label in the DSPLIMIT Set. It can be used to specify the cutback trigger + criterion as a limit on the maximum degree-of-freedom increment within a time step, considering all + degrees of freedom in an analysis (see :ref:`DSPLIMIT label description above). + ` + + .. _CUTCONTROL_physicsLimitSet: + + Physics Limit Set + ^^^^^^^^^^^^^^^^^ + + The physics limit set comprises the following labels: ULIMIT, ROTLIMIT, TEMPLIMIT, PRESLIMIT, + VOLTLIMIT, EMFLIMIT, MAGLIMIT, ALIMIT, CONCLIMIT. They can be used to specify distinct degree-of- + freedom limits as cutback triggers for individual physics in a multiphysics analysis. Whenever one + of these distinct limits is encountered, a cutback is triggered. + + Degree-of-freedom limits as cutback trigger criteria are specified via :ref:`cutcontrol` with labels + from either the DSPLIMIT set or the physics limit set. If multiple :ref:`cutcontrol` commands + include labels from both of these sets, the last command issued determines whether the cutback + trigger criteria is set by the DSPLIMIT or the physics limit set (see :ref:`example command listing + snippets below). ` + + .. _CUTCONTROL_PhysicsLimitSetDefault: + + .. rubric:: **Command Default: If no :ref:`cutcontrol` commands are issued with labels from the DSPLIMIT set or the physics limit set, the default cutback trigger criterion is DSPLIMIT with VALUE = 1.0 x 10 :sup:`7`.** + + Creep and Viscoelastic Analyses + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + For creep and viscoelastic analyses, the cutback procedure is similar; the process continues until + the minimum specified time step size is reached. However, if the criterion is exceeded, the program + issues a warning but continues the substep until the analysis is complete. In this case, convergence + is achieved but the criterion is not satisfied. + + :ref:`cutcontrol` enables a step size reduction for analyses experiencing convergence difficulties; + :ref:`opncontrol` is an analogous but opposite command that increases the step size to speed up + converging analyses. + + **Example Usage** + + .. _CUTCONTROL_examples: + + * `Friction Stir Welding Simulation (specify PLSLIMIT on CUTCONTROL) + `_ + CUTCONTROL ) + * Wire Crimping Simulation (specify PLSLIMIT on :ref:`cutcontrol` ) + * Control the maximum incremental pore pressure allowed in a time step via DPPLIMIT on + :ref:`cutcontrol` + * `Regularized Microplane Damage Models (specify MDMG on CUTCONTROL) + `_ CUTCONTROL ) + + .. _CUTCONTROL_CMDlistingPysLimitDSPLimit: + + Multiple :ref:`cutcontrol` Commands with labels from both the DSPLIMIT and the Physics Limit Sets + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + When multiple :ref:`cutcontrol` commands include labels from both the DSPLIMIT and the physics limit + sets, DSPLIMIT is ignored unless ``Lab`` = DSPLIMIT on the last :ref:`cutcontrol` command issued as + illustrated in the examples below. + + * **Label** **on the last** :ref:`cutcontrol` command issued is from the physics limit set : The + cutback trigger criteria are those specified by the physics limit set, and the earlier + :ref:`cutcontrol`,DSPLIMIT command is ignored. + + .. code:: apdl + + CUTCONTROL,TEMPLIMIT,10 CUTCONTROL,DSPLIMIT,0.7 CUTCONTROL,ULIMIT,0.2 !trigger criteria + is specified by physics limit set (and DSPLIMIT is ignored) !both ULIMIT and TEMPLIMIT + contribute to the physics limit set of cutback trigger criteria + + * **Lab= DSPLIMIT on the last** :ref:`cutcontrol` command issued : DSPLIMIT sets the cutback trigger + criterion and earlier :ref:`cutcontrol` command(s) issued with ``Lab`` = labels from the physics + limit set are ignored. + + .. code:: apdl + + CUTCONTROL,TEMPLIMIT,10 CUTCONTROL,ULIMIT,0.2 CUTCONTROL,DSPLIMIT,0.7 !trigger criteria is + specified by DSPLIMIT (and physics limit set labels are ignored) """ command = f"CUTCONTROL,{lab},{value},{option}" return self.run(command, **kwargs) - def ddoption(self, decomp="", nprocpersol="", numsolforlp="", **kwargs): - """Sets domain decomposer option for Distributed ANSYS. + def ddoption( + self, decomp: str = "", nprocpersol: str = "", numsolforlp: str = "", **kwargs + ): + r"""Sets domain decomposer option for a distributed-memory parallel (DMP) solution. + + Mechanical APDL Command: `DDOPTION `_ - APDL Command: DDOPTION + **Command default:** + + .. _DDOPTION_default: + + The optimal algorithm for domain decomposition is automatically chosen. Parameters ---------- - Decomp + decomp : str Controls which domain decomposition algorithm to use. - * AUTO - Automatically selects the optimal domain decomposition method (default). - * MESH - Decompose the FEA mesh. - * FREQ - Decompose the frequency domain for harmonic analyses. - * CYCHI -Decompose the harmonic indices for cyclic symmetry modal analyses. + * ``AUTO`` - Automatically selects the optimal domain decomposition method (default). + + * ``MESH`` - Decompose the FEA mesh. + + * ``FREQ`` - Decompose the frequency domain for harmonic analyses. - nprocpersol - Number of processes to be used for mesh-based decomposition in conjunction with each frequency solution (`Decomp = FREQ`) or harmonic index solution (`Decomp = CYCHI`). Defaults to 1. This field - is ignored when `Decomp = MESH`. + * ``CYCHI`` - Decompose the harmonic indices for cyclic symmetry modal analyses. - numsolforlp - Number of frequency or harmonic index solutions in a subsequent linear perturbation harmonic or linear perturbation cyclic modal analysis. This field is ignored when `Decomp = MESH` + nprocpersol : str + Number of processes to be used for mesh-based decomposition in conjunction with each frequency + solution ( ``Decomp`` = FREQ) or harmonic index solution ( ``Decomp`` = CYCHI). Defaults to 1. + This field is ignored when ``Decomp`` = MESH. + + numsolforlp : str + Number of frequency or harmonic index solutions in a subsequent linear perturbation harmonic or + linear perturbation cyclic modal analysis. This field is ignored when ``Decomp`` = MESH. Notes ----- - This command controls options relating to the domain decomposition - algorithm used by Distributed ANSYS to split the model into pieces (or - domains), with each piece being solved on a different processor. - - The greedy domain decomposition algorithm starts from a single element - at a corner of the model. The domain grows by taking the properly - connected neighboring elements and stops after reaching the optimal - size. - - The METIS domain decomposition algorithm starts by creating a graph - from the finite element mesh. It then uses a multilevel graph - partitioning scheme which reduces the size of the original graph, - creates domains using the reduced graph, and then creates the final CPU - domains by expanding the smaller domains from the reduced graph back to - the original mesh. + + .. _DDOPTION_notes: + + This command controls options related to the domain decomposition algorithm used in a distributed- + memory parallel (DMP) solution to split the analysis calculations into domains, with each domain + being solved on a different process. + + By default, the optimal domain decomposition algorithm (MESH, FREQ, or CYCHI) is automatically + chosen. When FREQ (for a harmonic analysis) or CYCHI (for a cyclic symmetry modal analysis) is + automatically chosen, the ``NPROCPERSOL`` argument is also automatically set to a value ≥ 1. + + The "mesh" algorithm ( ``Decomp`` = MESH) divides the finite element mesh into domains. In this + case, domains are effectively groups of elements, with one domain being solved on each process. This + algorithm seeks to create evenly sized domains (that is, domains with equal numbers of elements) as + well as to minimize the size of interfaces between the newly created domains. This algorithm can be + used for all analysis types. + + The "frequency" algorithm ( ``Decomp`` = FREQ) divides the specified frequency range for a harmonic + analysis into domains. In this case, domains are effectively groups of frequency solutions, with one + domain being solved on ``NPROCPERSOL`` processes. If there are more processes than frequency points, + some processes will remain idle during the harmonic analysis solution. This algorithm seeks to + create evenly sized domains. However, if the number of processes does not divide evenly into the + number of frequency solutions, the efficiency of the parallel solution will be reduced. This + algorithm can only be used for harmonic analyses using the auto ( :ref:`hropt`,AUTO), full ( + :ref:`hropt`,FULL), or frequency-sweep ( :ref:`hropt`,VT) method. + + The "cyclic" algorithm ( ``Decomp`` = CYCHI) divides the specified list of harmonic indices for a + cyclic symmetry modal analysis into domains. In this case, domains are effectively groups of cyclic + harmonic indices, with one domain being solved on ``NPROCPERSOL`` processes. If there are more + processes than harmonic indices, some processes will remain idle during the cyclic model solution. + This algorithm seeks to create evenly sized domains. However, if the number of processes does not + divide evenly into the number of harmonic indices, the efficiency of the parallel solution will be + reduced. + + For the mesh algorithm (MESH), all available processes are used. This is not necessarily the case + for the frequency and cyclic algorithms (FREQ and CYCHI). + + ``NPROCPERSOL`` is only used when ``Decomp`` = FREQ or CYCHI. It defaults to 1, which essentially + means that no mesh-based domain decomposition occurs. When ``NPROCPERSOL`` is defined to be greater + than 1, a combination of FREQ or CYCHI decomposition and MESH decomposition is employed. As an + example, consider a harmonic analysis with 50 requested frequency points ( :ref:`nsubst`,50) that + uses distributed processing with 100 CPU cores ( -dis -np 100). Specifying :ref:`ddoption`,FREQ,2 + would lead to 50 parallel sets of calculations, each working on a different frequency point and + using 2 cores for mesh-based domain decomposition (that is, 2 groups of elements per frequency). + + :ref:`ddoption` must be issued prior to solving the first load step. Once the first load step is + completed, this command cannot be used to change the domain decomposition method. The only exception + is for analyses which use the linear perturbation procedure. + + In a linear perturbation analysis, :ref:`ddoption` must be entered prior to the :ref:`solve`,ELFORM + command. In addition, the number of frequency solutions (in a subsequent harmonic analysis) or + harmonic index solutions (in a subsequent cyclic modal analysis) must be input via the + ``NUMSOLFORLP`` argument to enable proper domain decomposition to occur at the :ref:`solve`,ELFORM + stage of the linear perturbation analysis. For more information, see `Linear Perturbation Analysis + `_ + + For more information and recommendations on how to choose the domain decomposition method, see. + + For the frequency and the cyclic algorithms, solution information for the harmonic frequencies ( + ``Decomp`` = FREQ) or cyclic harmonic indices ( ``Decomp`` = CYCHI) solved by the worker processes + is only written to the output files for those processes ( :file:`Jobnamen.OUT` ). See for more + information. """ command = f"DDOPTION,{decomp},{nprocpersol},{numsolforlp}" return self.run(command, **kwargs) def dmpext( self, - smode="", - tmode="", - dmpname="", - freqb="", - freqe="", - nsteps="", + smode: str = "", + tmode: str = "", + dmpname: str = "", + freqb: str = "", + freqe: str = "", + nsteps: str = "", **kwargs, ): - """Extracts modal damping coefficients in a specified frequency range. + r"""Extracts modal damping coefficients in a specified frequency range. - APDL Command: DMPEXT + Mechanical APDL Command: `DMPEXT `_ Parameters ---------- - smode - Source mode number. There is no default for this field; you must - enter an integer greater than zero. + smode : str + Source mode number. There is no default for this field; you must enter an integer greater than + zero. - tmode - Target mode. Defaults to SMODE. + tmode : str + Target mode. Defaults to ``SMODE``. - dmpname - Array parameter name containing the damping results. Defaults to - d_damp. + dmpname : str + Array parameter name containing the damping results. Defaults to :file:`d_damp`. - freqb - Beginning frequency range (real number greater than zero) or 'EIG' - at eigenfrequency of source mode. 'EIG' is valid only if SMODE = - TMODE. Note that EIG must be enclosed in single quotes when this - command is used on the command line or in an input file. There is - no default for this field; you must enter a value. + freqb : str + Beginning frequency range (real number greater than zero) or 'EIG' at eigenfrequency of source + mode. 'EIG' is valid only if ``SMODE`` = ``TMODE``. Note that EIG must be enclosed in single + quotes when this command is used on the command line or in an input file. There is no default + for this field; you must enter a value. - freqe - End of frequency range. Must be blank for Freqb = EIG. Default is - Freqb. + freqe : str + End of frequency range. Must be blank for ``Freqb`` = EIG. Default is ``Freqb``. - nsteps + nsteps : str Number of substeps. Defaults to 1. Notes ----- - DMPEXT invokes an ANSYS macro that uses modal projection techniques to - compute the damping force by the modal velocity of the source mode onto - the target mode. From the damping force, damping parameters are - extracted. DMPEXT creates an array parameter Dmpname, with the - following entries in each row: - response frequency + .. _DMPEXT_notes: - modal damping coefficient + DMPEXT invokes a Mechanical APDL macro that uses modal projection techniques to compute the damping + force + by the modal velocity of the source mode onto the target mode. From the damping force, damping + parameters are extracted. DMPEXT creates an array parameter ``Dmpname``, with the following entries + in each row: - modal squeeze stiffness coefficient + * response frequency - damping ratio + * modal damping coefficient - squeeze-to-structural stiffness ratio + * modal squeeze stiffness coefficient - The macro requires the modal displacements from the file Jobname.EFL - obtained from the RMFLVEC command. In addition, a node component FLUN - must exist from all FLUID136 nodes. The computed damping ratio may be - used to specify constant or modal damping by means of the DMPRAT or - MDAMP commands. For Rayleigh damping, use the ABEXTRACT command to - compute ALPHAD and BETAD damping parameters. See Thin Film Analysis for - more information on thin film analyses. + * damping ratio - The macro uses the LSSOLVE command to perform two load steps for each - frequency. The first load case contains the solution of the source - mode excitation and can be used for further postprocessing. Solid model - boundary conditions are deleted from the model. In addition, - prescribed nodal boundary conditions are applied to the model. You - should carefully check the boundary conditions of your model prior to - executing a subsequent analysis. + * squeeze-to-structural stiffness ratio - This command is also valid in PREP7. + The macro requires the modal displacements from the file :file:`Jobname.EFL` obtained from the + :ref:`rmflvec` command. In addition, a node component FLUN must exist from all ``FLUID136`` nodes. + The computed damping ratio may be used to specify constant or modal damping by means of the + :ref:`dmprat` or :ref:`mdamp` commands. For Rayleigh damping, use the :ref:`abextract` command to + compute ALPHAD and BETAD damping parameters. See Thin Film Analysis for more information on + thin film analyses. - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + The macro uses the :ref:`lssolve` command to perform two load steps for each frequency. The first + load case contains the solution of the source mode excitation and can be used for further + postprocessing. Solid model boundary conditions are deleted from the model. In addition, prescribed + nodal boundary conditions are applied to the model. You should carefully check the boundary + conditions of your model prior to executing a subsequent analysis. + + This command is also valid in PREP7. Distributed-Memory Parallel (DMP) Restriction This command is + not supported in a DMP solution. """ command = f"DMPEXT,{smode},{tmode},{dmpname},{freqb},{freqe},{nsteps}" return self.run(command, **kwargs) - def dmpoption(self, filetype="", combine="", rescombfreq="", deleopt="", **kwargs): - """Specifies distributed memory parallel (Distributed ANSYS) file + def dmpoption( + self, + filetype: str = "", + combine: str = "", + rescombfreq: str = "", + deleopt: str = "", + **kwargs, + ): + r"""Specifies distributed-memory parallel ( DMP ) file combination options. + + Mechanical APDL Command: `DMPOPTION `_ + + **Command default:** + + .. _DMPOPTION_default: - APDL Command: DMPOPTION - combination options. + Local solution files are automatically combined into a single global file upon leaving the solution + processor (for example, :file:`JobnameN.RST` files are combined into one :file:`Jobname.RST` file). + This is true for all files except the :file:`.Rnnn` files. Because they may be required in a + subsequent analysis, local files are not automatically deleted after combination. Parameters ---------- - filetype - Type of solution file to combine after a distributed memory - parallel solution. There is no default; if (blank), the command is - ignored. + filetype : str + Type of solution file to combine after a distributed memory parallel solution. There is no default; + if (blank), the command is ignored. - RST - Results files (.RST, .RTH, .RMG, .RSTP) + * ``RST`` - Results files ( :file:`.RST`, :file:`.RTH`, :file:`.RMG`, :file:`.RSTP` ) - EMAT - Element matrix files (.EMAT). + * ``EMAT`` - Element matrix files ( :file:`.EMAT` ). - ESAV - Element saved data files (.ESAVE) + * ``ESAV`` - Element saved data files ( :file:`.ESAV` ) - MODE - Modal results files (.MODE) + * ``MODE`` - Modal results files ( :file:`.MODE` ) - MLV - Modal load vector file (.MLV) + * ``MLV`` - Modal load vector file ( :file:`.MLV` ) - IST - Initial state file (.IST) + * ``IST`` - Initial state file ( :file:`.IST` ) - FULL - Full matrix file (.FULL) + * ``FULL`` - Full matrix file ( :file:`.FULL` ) - RFRQ - Reduced complex displacement file (.RFRQ) + * ``RFRQ`` - Reduced complex displacement file ( :file:`.RFRQ` ) - RDSP - Reduced displacement file (.RDSP) + * ``RDSP`` - Reduced displacement file ( :file:`.RDSP` ) - combine + * ``RNNN`` - Multiframe restart files ( :file:`.Rnnn` ) + + combine : str Option to combine solution files. - Yes - Combine solution files (default). + * ``Yes`` - Combine solution files (default for all files except the :file:`.Rnnn` files). - No - Do not combine solution files. + * ``No`` - Do not combine solution files (default for the :file:`.Rnnn` files only). - rescombfreq - Frequency used to combine the local results files during a distributed memory parallel solution. This option applies only when FileType = RST and Combine = YES. + rescombfreq : str + Frequency used to combine the local results files during a distributed memory parallel solution. + This option applies only when ``FileType`` = RST and ``Combine`` = YES. - NONE - Do not combine the local results files during solution. The local results files is combined only upon leaving the solution processor (default). + * ``NONE`` - Do not combine the local results files during solution. The local results files is + combined only upon leaving the solution processor (default). - ALL - Combines the local results files at every time point. + * ``ALL`` - Combines the local results files at every time point. - LAST - Combines the local results files at the last time point of every load step. + * ``LAST`` - Combines the local results files at the last time point of every load step. - deleopt - Option to delete local solution files of the type specified by FileType option after they are combined. This option applies only when Combine = Yes. + deleopt : str + Option to delete local solution files of the type specified by ``FileType`` option after they are combined. This option applies only when ``Combine`` = Yes. - Yes - Delete the local solution files after they are combined. + * ``Yes`` - Delete the local solution files after they are combined. - No - Do not delete the local solution files after they are combined (default). + * ``No`` - Do not delete the local solution files after they are combined (default). Notes ----- - The DMPOPTION command controls how solution files are written during a - distributed memory parallel (Distributed ANSYS) solution. This command - is most useful for controlling how results files (.RST,.RTH, etc.) are - written. - - In a distributed memory parallel solution, a local results file is - written by each process (JobnameN.ext, where N is the process number). - By default, the program automatically combines the local results files - (for example, JobnameN.RST) upon leaving the SOLUTION processor (for - example, upon the FINISH command) into a single global results file - (Jobname.RST) which can be used in ANSYS postprocessing. To reduce the - amount of communication and I/O performed by this operation, you can - issue the command DMPOPTION,RST,NO to bypass this step of combining the - local results files; the local files will remain on the local disks in - the current working directory. You can then use the RESCOMBINE command - macro in the POST1 general postprocessor (/POST1) to read all results - into the database for postprocessing. - - The RESCOMBINE command macro is intended for use with POST1. If you - want to postprocess distributed parallel solution results using the - POST26 time-history postprocessor (/POST26), it is recommended that you - combine your local results files into one global results file - (DMPOPTION,RST,YES or COMBINE). - - Local .EMAT, .ESAV, .MODE, .MLV, .IST, .RFRQ, .RDSP, and .FULL files - are also written (when applicable) by each process in a distributed - memory parallel solution. If these files are not needed for a - downstream solution or operation, you can issue the command - DMPOPTION,FileType,NO for each file type to bypass the file combination - step and thereby improve performance. You should not bypass the file - combination step if a downstream PSD analysis or modal expansion pass - will be performed. - - If DMPOPTION,MODE,NO or DMPOPTION,RST,NO is specified in a modal - analysis, element results cannot be written to the combined mode file - (Jobname.MODE). In this case, if Distributed ANSYS is used in a - downstream harmonic or transient analysis that uses the mode- - superposition method, the MSUPkey on the MXPAND command can retain its - value. However, if shared memory parallel processing is used in the - downstream harmonic or transient analysis, the MSUPkey is effectively - set to NO. - - The DMPOPTION command can be changed between load steps; however, doing - so will not affect which set of solution files are combined. Only the - last values of FileType and Combine upon leaving the solution processor - will be used to determine whether the solution files are combined. For - example, given a two load step solution and FileType = RST, setting - Combine = NO for the first load step and YES for the second load step - will cause all sets on the local results files to be combined. If the - opposite is true (Combine = YES for the first load step and NO for the - second load step), no results will be combined. - - After using DMPOPTION to suppress file combination, you may find it - necessary to combine the local files for a specific FileType for use in - a subsequent analysis. In this case, use the COMBINE command to combine - local solution files into a single, global file. + + .. _DMPOPTION_notes: + + The :ref:`dmpoption` command controls how solution files are written during a distributed-memory + parallel ( DMP ) solution. This command is most useful for controlling how results files ( + :file:`.rst`, :file:`.rth`, etc.) are written. + + In a distributed memory parallel solution, a local results file is written by each process ( + :file:`JobnameN.ext`, where ``N`` is the process number). By default, the program automatically + combines the local results files (for example, :file:`JobnameN.rst` ) upon leaving the solution + processor (for example, upon the :ref:`finish` command) into a single global results file ( + :file:`Jobname.rst` ) which can be used in postprocessing. + + Alternatively, the ``ResCombFreq`` argument can be used to combine the local results files at + certain time points during the distributed solution to create a single combined results file that + can be used to postprocess the model while the solution progresses. Doing so increases data + communication and I/O between processes, leading to slower performance. + + The ``ResCombFreq`` option only applies when solving static analyses, and harmonic or transient + analyses that use the full method. It does not apply to mode superposition harmonic and mode + superposition transient analyses. It does not apply when using the frequency domain decomposition + option ( :ref:`ddoption`,FREQ) in a harmonic analysis. + + To reduce communication and I/O, issue :ref:`dmpoption`,RST,NO to bypass this step of combining the + local results files; the local files remain on the local disks in the current working directory. You + can then use :ref:`rescombine` in the POST1 general postprocessor ( :ref:`post1` ) to read all + results into the database for postprocessing. + + The :ref:`rescombine` command macro is intended for use with POST1. If you want to postprocess + distributed parallel solution results using the POST26 time-history postprocessor ( :ref:`post26` ), + it is recommended that you combine your local results files into one global results file ( + :ref:`dmpoption`,RST,YES or :ref:`combine` ). + + Local :file:`.emat`, :file:`.esav`, :file:`.mode`, :file:`.mlv`, :file:`.ist`, :file:`.rfrq`, + :file:`.rdsp`, and :file:`.full` files are also written (when applicable) by each process in a + distributed memory parallel solution. If these files are not needed for a downstream solution or + operation, you can issue the command :ref:`dmpoption`, ``FileType``,NO for each file type to bypass + the file combination step and thereby improve performance. + + If :ref:`dmpoption`,MODE,NO or :ref:`dmpoption`,RST,NO is specified in a modal analysis, element + results cannot be written to the combined mode file ( :file:`Jobname.MODE` ). In this case, if + distributed-memory parallel processing is used in a downstream harmonic or transient analysis that + uses the mode-superposition method, the ``MSUPkey`` on the :ref:`mxpand` command can retain its + value. However, if shared-memory parallel processing is used in the downstream harmonic or transient + analysis, the ``MSUPkey`` is effectively set to NO. + + If :ref:`dmpoption`,RNNN,YES is specified, all multiframe restart files named :file:`Jobname.R001` + to :file:`Jobname.R999` are automatically combined upon leaving the solution processor (which can be + slow and inefficient). To manually combine a single set of :file:`.Rnnn` restart files, use the + :ref:`combine` command. + + Since local solution files may be required in a downstream analysis, the option to delete them after + combination is disabled ( ``DeleOpt`` = No) by default. However, you can enable this option to + reduce disk space usage by removing certain files if you know that they are not needed in any + subsequent analysis. + + :ref:`dmpoption` can be changed between load steps; however, doing so does not affect which set of + solution files are combined. The values of ``Combine`` and ``DeleOpt`` are overwritten if + :ref:`dmpoption` is issued multiple times for the same ``FileType``. As a result, only the last + values of ``Combine`` and ``DeleOpt`` for each ``FileType`` upon leaving the solution processor + determine whether the local solution files are combined with or without deletion. For example, in a + two-load-step solution, if :ref:`dmpoption`, RST, NO is issued in the first load step and + :ref:`dmpoption`, RST, YES,,YES is issued in the second load step, all sets on the local results + files will be combined, and then the local results files will be deleted. If the opposite is true ( + :ref:`dmpoption`, RST, YES,,YES is issued in the first load step, and :ref:`dmpoption`, RST, NO is + issued in the second load step), no results files are combined, and thus no local results files are + deleted. + + After using :ref:`dmpoption` to suppress file combination, you may find it necessary to combine the + local files for a specific ``FileType`` for use in a subsequent analysis. In this case, use the + :ref:`combine` command to combine local solution files into a single, global file. """ - command = f"DMPOPTION,{filetype},{combine}{rescombfreq},{deleopt}" + command = f"DMPOPTION,{filetype},{combine},{rescombfreq},{deleopt}" return self.run(command, **kwargs) def dspoption( self, - reord_option="", - memory_option="", - memory_size="", - solve_info="", + reord_option: str = "", + memory_option: str = "", + memory_size: str = "", + solve_info: str = "", **kwargs, ): - """Sets memory option for the distributed sparse solver. + r"""Sets memory option for the sparse solver. + + Mechanical APDL Command: `DSPOPTION `_ + + **Command default:** - APDL Command: DSPOPTION + .. _DSPOPTION_default: + + Automatic memory allocation is used. Parameters ---------- - reord_option + reord_option : str Reordering option: - DEFAULT - Use the default reordering scheme. - - SEQORDER - Use a sequential equation reordering scheme - within the distributed sparse solver. Relative - to PARORDER, this option typically results in - longer equation ordering times and therefore - longer overall solver times. Occasionally, - however, this option will produce better - quality orderings which decrease the matrix - factorization times and improve overall solver - performance. - - PARORDER - Use a parallel equation reordering scheme - within the distributed sparse solver. Relative - to SEQORDER, this option typically results in - shorter equation ordering times and therefore - shorter overall solver times. Occasionally, - however, this option will produce lower quality - orderings which increase the matrix - factorization times and degrade overall solver - performance. - - memory_option + * ``DEFAULT`` - Use the default reordering scheme. + + * ``SEQORDER`` - Use a sequential equation reordering scheme. Relative to PARORDER, this option + typically results in longer equation ordering times and therefore longer overall solver times. + Occasionally, however, this option will produce better quality orderings which decrease the matrix + factorization times and improve overall solver performance. + + * ``PARORDER`` - Use a parallel equation reordering scheme. Relative to SEQORDER, this option + typically results in shorter equation ordering times and therefore shorter overall solver times. + Occasionally, however, this option will produce lower quality orderings which increase the matrix + factorization times and degrade overall solver performance. + + memory_option : str Memory allocation option: - DEFAULT - Use the default memory allocation strategy for - the distributed sparse solver. The default - strategy attempts to run in the INCORE memory - mode. If there is not enough physical memory - available when the solver starts to run in the - INCORE memory mode, the solver will then attempt - to run in the OUTOFCORE memory mode. - - INCORE - Use a memory allocation strategy in the - distributed sparse solver that will attempt to - obtain enough memory to run with the entire - factorized matrix in memory. This option uses the - most amount of memory and should avoid doing any - I/O. By avoiding I/O, this option achieves - optimal solver performance. However, a - significant amount of memory is required to run - in this mode, and it is only recommended on - machines with a large amount of memory. If the - allocation for in-core memory fails, the solver - will automatically revert to out-of-core memory - mode. - - OUTOFCORE - Use a memory allocation strategy in the - distributed sparse solver that will attempt to - allocate only enough work space to factor each - individual frontal matrix in memory, but will - share the entire factorized matrix on - disk. Typically, this memory mode results in - poor performance due to the potential - bottleneck caused by the I/O to the various - files written by the solver. - - FORCE - This option, when used in conjunction with the - Memory_Size option, allows you to force the - distributed sparse solver to run with a specific - amount of memory. This option is only recommended - for the advanced user who understands distributed - sparse solver memory requirements for the problem - being solved, understands the physical memory on - the system, and wants to control the distributed - sparse solver memory usage. - - memory_size - Initial memory size allocation for the sparse solver in - MB. The Memory_Size setting should always be well within - the physical memory available, but not so small as to - cause the distributed sparse solver to run out of - memory. Warnings and/or errors from the distributed sparse - solver will appear if this value is set too low. If the - FORCE memory option is used, this value is the amount of - memory allocated for the entire duration of the - distributed sparse solver solution. - - solve_info + * ``DEFAULT`` - Use the default memory allocation strategy for the sparse solver. The default + strategy attempts to run in the INCORE memory mode. If there is not enough physical memory available + when the solver starts to run in the INCORE memory mode, the solver will then attempt to run in the + OUTOFCORE memory mode. + + * ``INCORE`` - Use a memory allocation strategy in the sparse solver that will attempt to obtain + enough memory to run with the entire factorized matrix in memory. This option uses the most amount + of memory and should avoid doing any I/O. By avoiding I/O, this option achieves optimal solver + performance. However, a significant amount of memory is required to run in this mode, and it is only + recommended on machines with a large amount of memory. If the allocation for in-core memory fails, + the solver will automatically revert to out-of-core memory mode. + + * ``OUTOFCORE`` - Use a memory allocation strategy in the sparse solver that will attempt to + allocate only enough work space to factor each individual frontal matrix in memory, but will share + the entire factorized matrix on disk. Typically, this memory mode results in poor performance due to + the potential bottleneck caused by the I/O to the various files written by the solver. + + * ``FORCE`` - This option, when used in conjunction with the ``Memory_Size`` option, allows you to + force the sparse solver to run with a specific amount of memory. This option is only recommended for + the advanced user who understands sparse solver memory requirements for the problem being solved, + understands the physical memory on the system, and wants to control the sparse solver memory usage. + + memory_size : str + Initial memory size allocation for the sparse solver for each process ( ``Memory_Size`` /process + in GB ). The ``Memory_Size`` setting should always be well within the physical memory available, + but not so small as to cause the sparse solver to run out of memory. Warnings and/or errors from + the sparse solver will appear if this value is set too low. If the FORCE memory option is used, + this value is the amount of memory allocated for the entire duration of the sparse solver + solution. + + solve_info : str Solver output option: - OFF - Turns off additional output printing from the - distributed sparse solver (default). + * ``OFF`` - Turns off additional output printing from the sparse solver (default). - PERFORMANCE - Turns on additional output printing from the - distributed sparse solver, including a - performance summary and a summary of file - I/O for the distributed sparse - solver. Information on memory usage during - assembly of the global matrix (that is, - creation of the Jobname.FULL file) is also - printed with this option. + * ``PERFORMANCE`` - Turns on additional output printing from the sparse solver, including a + performance summary and a summary of file I/O for the sparse solver. Information on memory usage + during assembly of the global matrix (that is, creation of the :file:`Jobname.FULL` file) is also + printed with this option. Notes ----- - This command controls options related to the distributed sparse solver - in all analysis types where the distributed sparse solver can be used. - - The amount of memory required for the distributed sparse solver is - unknown until the matrix structure is preprocessed, including equation - reordering. The amount of memory allocated for the distributed sparse - solver is then dynamically adjusted to supply the solver what it needs - to compute the solution. - - If you have a large memory system, you may want to try selecting the - INCORE memory mode for larger jobs to improve performance. Also, when - running the distributed sparse solver with many processors on the same - machine or on a machine with very slow I/O performance (e.g., slow hard - drive speed), you may want to try using the INCORE memory mode to - achieve better performance. However, doing so may require much more - memory compared to running in the OUTOFCORE memory mode. - - Running with the INCORE memory mode is best for jobs which comfortably - fit within the limits of the physical memory on a given system. If the - distributed sparse solver workspace exceeds physical memory size, the - system will be forced to use virtual memory (or the system page/swap - file). In this case, it is typically more efficient to run with the - OUTOFCORE memory mode. + + .. _DSPOPTION_notes: + + This command controls options related to the sparse solver in all analysis types where this solver + can be used. + + The amount of memory required for the sparse solver is unknown until the matrix structure is + preprocessed, including equation reordering. The amount of memory allocated for the sparse solver is + then dynamically adjusted to supply the solver what it needs to compute the solution. + + If you have a large memory system, you may want to try selecting the INCORE memory mode for larger + jobs to improve performance. Also, when running the sparse solver with many processors on the same + machine or on a machine with very slow I/O performance (for example, slow hard drive speed), you may + want to try using the INCORE memory mode to achieve better performance. However, doing so may + require much more memory compared to running in the OUTOFCORE memory mode. + + Running with the INCORE memory mode is best for jobs which comfortably fit within the limits of the + physical memory on a given system. If the sparse solver workspace exceeds physical memory size, the + system will be forced to use virtual memory (or the system page/swap file). In this case, it is + typically more efficient to run with the OUTOFCORE memory mode. """ command = ( f"DSPOPTION,{reord_option},{memory_option},{memory_size},,,{solve_info}" ) return self.run(command, **kwargs) + def ematwrite(self, key: str = "", **kwargs): + r"""Forces the writing of all the element matrices to :file:`Jobname.emat` None. + + Mechanical APDL Command: `EMATWRITE `_ + + Parameters + ---------- + key : str + Write key: + + * ``YES`` - Forces the writing of the element matrices to :file:`Jobname.emat` None even if not + normally done. + + * ``NO`` - Element matrices are written only if required. This value is the default. + + Notes + ----- + + .. _EMATWRITE_notes: + + The :ref:`ematwrite` command forces Mechanical APDL to write the :file:`Jobname.emat` file. + + If used in the solution processor ( :ref:`slashsolu` ), this command is valid within the first load + step only. + + This command is also valid in PREP7. + """ + command = f"EMATWRITE,{key}" + return self.run(command, **kwargs) + + def eqslv( + self, + lab: str = "", + toler: str = "", + mult: str = "", + keepfile: str = "", + **kwargs, + ): + r"""Specifies the type of equation solver. + + Mechanical APDL Command: `EQSLV `_ + + **Command default:** + + .. _EQSLV_default: + + The sparse direct solver is the default solver for all analyses, with the exception of + modal/buckling analyses. + + For modal/buckling analyses, there is no default solver. You must specify a solver with the + :ref:`modopt` or :ref:`bucopt` command. The specified solver automatically chooses the required + internal equation solver (for example, :ref:`modopt` ,LANPCG automatically uses :ref:`eqslv`,PCG + internally, and :ref:`bucopt`,LANB automatically uses :ref:`eqslv`,SPARSE internally). + + Parameters + ---------- + lab : str + Equation solver type: + + * ``SPARSE`` - Sparse direct equation solver. Applicable to real-value or complex-value symmetric + and unsymmetric matrices. Available only for STATIC, HARMIC (full method only), TRANS (full method + only), SUBSTR, and PSD spectrum analysis types ( :ref:`antype` ). Can be used for nonlinear and + linear analyses, especially nonlinear analysis where indefinite matrices are frequently encountered. + Well suited for contact analysis where contact status alters the mesh topology. Other typical well- + suited applications are: (a) models consisting of shell/beam or shell/beam and solid elements (b) + models with a multi-branch structure, such as an automobile exhaust or a turbine fan. This is an + alternative to iterative solvers since it combines both speed and robustness. Generally, it requires + considerably more memory (~10x) than the PCG solver to obtain optimal performance (running totally + in-core). When memory is limited, the solver works partly in-core and out-of-core, which can + noticeably slow down the performance of the solver. See the :ref:`bcsoption` command for more + details on the various modes of operation for this solver. + + This solver can be run using shared-memory parallel (SMP), distributed-memory parallel (DMP), or + hybrid parallel processing. For DMP, this solver preserves all of the merits of the classic or + shared memory sparse solver. The total sum of memory (summed for all processes) is usually higher + than the shared memory sparse solver. System configuration also affects the performance of the + distributed memory parallel solver. If enough physical memory is available, running this solver in + the in-core memory mode achieves optimal performance. The ideal configuration when using the out-of- + core memory mode is to use one processor per machine on multiple machines (a cluster), spreading the + I/O across the hard drives of each machine, assuming that you are using a high-speed network such as + Infiniband to efficiently support all communication across the multiple machines. + + This solver supports use of the `GPU accelerator capability + `_. + + * ``JCG`` - Jacobi Conjugate Gradient iterative equation solver. Available only for STATIC, HARMIC + (full method only), and TRANS (full method only) analysis types ( :ref:`antype` ). Can be used for + structural, thermal, and multiphysics applications. Applicable for symmetric, unsymmetric, complex, + definite, and indefinite matrices. Recommended for 3D harmonic analyses in structural and + multiphysics applications. Efficient for heat transfer, electromagnetics, piezoelectrics, and + acoustic field problems. + + This solver can be run using shared-memory parallel (SMP), distributed-memory parallel (DMP), or + hybrid parallel processing. For DMP, in addition to the limitations listed above, this solver only + runs in a distributed parallel fashion for STATIC and TRANS (full method) analyses in which the + stiffness is symmetric and only when not using the fast thermal option ( :ref:`thopt` ). Otherwise, + this solver disables distributed-memory parallelism at the onset of the solution, and shared-memory + parallelism is used instead. + + This solver supports use of the `GPU accelerator capability + `_. When using the + GPU accelerator capability, in addition to the limitations listed above, this solver is available + only for STATIC and TRANS (full method) analyses where the stiffness is symmetric and does not + support the fast thermal option ( :ref:`thopt` ). + + * ``ICCG`` - Incomplete Cholesky Conjugate Gradient iterative equation solver. Available for STATIC, + HARMIC (full method only), and TRANS (full method only) analysis types ( :ref:`antype` ). Can be + used for structural, thermal, and multiphysics applications, and for symmetric, unsymmetric, + complex, definite, and indefinite matrices. The ICCG solver requires more memory than the JCG + solver, but is more robust than the JCG solver for ill-conditioned matrices. + + This solver can only be run in shared-memory parallel mode. If it is run in DMP mode, this solver + disables distributed-memory parallelism at the onset of the solution, and shared-memory parallelism + is used instead + + This solver does not support use of the `GPU accelerator capability + `_. + + * ``QMR`` - Quasi-Minimal Residual iterative equation solver. Available for the HARMIC (full method + only) analysis type ( :ref:`antype` ). Can be used for symmetric, complex, definite, and indefinite + matrices. The QMR solver is more stable than the ICCG solver. + + This solver can only be run in shared memory parallel mode and only supports 1 core. If it is run in + DMP mode, this solver disables distributed-memory parallelism at the onset of the solution, and + shared-memory parallelism is used instead + + This solver does not support use of the `GPU accelerator capability + `_. + + * ``PCG`` - Preconditioned Conjugate Gradient iterative equation solver (licensed from Computational + Applications and Systems Integration, Inc.). Requires less disk file space than SPARSE and is faster + for large models. Useful for plates, shells, 3D models, large 2D models, and other problems having + symmetric, sparse matrices. Such matrices are typically positive definite, but could be indefinite + for some nonlinear analyses. The PCG solver can also be used for single-field thermal analyses + involving unsymmetric matrices. Requires twice as much memory as JCG. Available only for analysis + types ( :ref:`antype` ) STATIC, TRANS (full method only), or MODAL (with PCG Lanczos option only). + Also available for the use pass of substructure analyses ( ``MATRIX50`` ). The PCG solver can + robustly handle models that involve the use of constraint and/or coupling equations ( :ref:`ce`, + :ref:`ceintf`, :ref:`cp`, :ref:`cpintf`, and :ref:`cerig` ). With this solver, you can use the + :ref:`msave` command to obtain a considerable memory savings. + + The PCG solver can handle ill-conditioned problems by using a higher level of difficulty (see + :ref:`pcgopt` ). Ill-conditioning arises from elements with high aspect ratios, contact, and + plasticity. + + This solver can be run in shared-memory parallel or distributed-memory parallel mode. In DMP mode, + this solver preserves all of the merits of the classic or shared-memory PCG solver. The total sum of + memory (summed for all processes) is about 30% more than the shared-memory PCG solver. + + This solver supports use of the `GPU accelerator capability + `_. + + toler : str + Iterative solver tolerance value. Used only with the Jacobi Conjugate Gradient, Incomplete + Cholesky Conjugate Gradient, Pre-conditioned Conjugate Gradient, and Quasi-Minimal Residual + equation solvers. For the PCG solver, the default is 1.0E-8. When using the PCG Lanczos mode + extraction method, the default solver tolerance value is 1.0E-4. For the JCG and ICCG solvers + with symmetric matrices, the default is 1.0E-8. For the JCG and ICCG solvers with unsymmetric + matrices, and for the QMR solver, the default is 1.0E-6. Iterations continue until the SRSS norm + of the residual is less than ``TOLER`` times the norm of the applied load vector. For the PCG + solver in the linear static analysis case, 3 error norms are used. If one of the error norms is + smaller than ``TOLER``, and the SRSS norm of the residual is smaller than 1.0E-2, convergence is + assumed to have been reached. See `Iterative Solver + `_ + + When used with the Pre-conditioned Conjugate Gradient equation solver, ``TOLER`` can be modified + between load steps (this is typically useful for nonlinear analysis). + + If a ``Lev_Diff`` value of 5 is specified on the :ref:`pcgopt` command (either program- or user- + specified), ``TOLER`` has no effect on the accuracy of the obtained solution from the PCG + solver; a direct solver is used when ``Lev_Diff`` = 5. + + mult : str + Multiplier (defaults to 2.5 for nonlinear analyses; 1.0 for linear analyses) used to control the + maximum number of iterations performed during convergence calculations. Used only with the Pre- + conditioned Conjugate Gradient equation solver (PCG). The maximum number of iterations is equal + to the multiplier ( ``MULT`` ) times the number of degrees of freedom (DOF). If ``MULT`` is + input as a negative value, then the maximum number of iterations is equal to abs( ``MULT`` ). + Iterations continue until either the maximum number of iterations or solution convergence has + been reached. In general, the default value for ``MULT`` is adequate for reaching convergence. + However, for ill- conditioned matrices (that is, models containing elements with high aspect + ratios or material type discontinuities) the multiplier may be used to increase the maximum + number of iterations used to achieve convergence. The recommended range for the multiplier is + 1.0 :math:`equation not available` ``MULT`` :math:`equation not available` 3.0. Normally, a + value greater than 3.0adds no further benefit toward convergence, and merely increases + timerequirements. If the solution does not converge with 1.0 :math:`equation not available` + ``MULT`` :math:`equation not available` 3.0, or in less than 10,000 iterations,then convergence + is highly unlikely and further examination of themodel is recommended. Rather than increasing + the default value of ``MULT``, consider increasing the level of difficulty ( ``Lev_Diff`` ) on + the :ref:`pcgopt` command. + + keepfile : str + Determines whether files from a SPARSE solver run should be deleted or retained. Applies only to + ``Lab`` = SPARSE for static and full transient analyses. + + * ``DELE`` - Deletes all files from the SPARSE solver run, including the factorized file, + :file:`.DSPsymb`, upon :ref:`finish` or ``/EXIT`` (default). + + * ``KEEP`` - Retains all necessary files from the SPARSE solver run, including the :file:`.DSPsymb` + file, in the working directory. + + Notes + ----- + + .. _EQSLV_notes: + + The selection of a solver can affect the speed and accuracy of a solution. For a more detailed + discussion of the merits of each solver, see `Solution + `_ in + the `Basic Analysis Guide + `_. + + This command is also valid in PREP7. + + Distributed-Memory Parallel (DMP) Restriction All equation solvers are supported in a DMP analysis. + However, the SPARSE and PCG solvers are the + only distributed solvers that always run a fully distributed solution. The JCG solver runs in a + fully distributed mode in some cases; in other cases, it does not. The ICCG and QMR solvers are not + distributed solvers; therefore, you will not see the full performance improvements with these + solvers that you would with a fully distributed solution. + """ + command = f"EQSLV,{lab},{toler},{mult},,{keepfile}" + return self.run(command, **kwargs) + + def eresx(self, key: str = "", **kwargs): + r"""Specifies extrapolation of integration-point results. + + Mechanical APDL Command: `ERESX `_ + + **Command default:** + + .. _ERESX_default: + + Extrapolate integration-point results to the nodes for all elements except those with active + plasticity, creep, or swelling nonlinearities (default). + + For coupled pore-pressure-thermal elements ( ``CPT212``, ``CPT213``, ``CPT215``, ``CPT216``, + ``CPT217`` ), the default behavior is to copy integration-point results to the nodes. + + Parameters + ---------- + key : str + Extrapolation key: + + * ``DEFA`` - If element is fully elastic (no active plasticity, creep, or swelling nonlinearities), + extrapolate the integration-point results to the nodes. If any portion of the element is plastic (or + other active material nonlinearity), copy the integration-point results to the nodes (default). + + * ``YES`` - Extrapolate the linear portion of the integration-point results to the nodes and copy + the nonlinear portion (for example, plastic strains). + + * ``NO`` - Copy the integration-point results to the nodes. + + Notes + ----- + + .. _ERESX_notes: + + Specifies whether the solution results at the element-integration points are extrapolated or copied + to the nodes for element and nodal postprocessing. Structural stresses, elastic and thermal strains, + field gradients, and fluxes are affected. Nonlinear data (such as plastic, creep, and swelling + strains) are always copied to the nodes, never extrapolated. For shell elements, :ref:`eresx` + applies only to integration-point results in the in-plane directions. + + Extrapolation occurs in the element-solution coordinate system. For elements allowing different + solution systems at integration points (such as ``SHELL281`` and ``SOLID186`` ), extrapolation can + produce unreliable results when the solution coordinate systems in each element differ + significantly. (Varying element-solution coordinate systems can be created via the :ref:`esys` + command or from large deformation.) Examine results carefully in such cases, and disable + extrapolation if necessary. + + This command is also valid in PREP7. + """ + command = f"ERESX,{key}" + return self.run(command, **kwargs) + def exbopt( self, - outinv2="", - outtcms="", - outsub="", - outcms="", - outcomp="", - outrm="", - noinv="", - outele="", + outinv2: int | str = "", + outtcms: int | str = "", + outsub: int | str = "", + outcms: int | str = "", + outcomp: int | str = "", + outrm: int | str = "", + noinv: int | str = "", + outele: int | str = "", **kwargs, ): - """Specifies .EXB file output options in a CMS generation pass. + r"""Specifies ``.EXB`` file output options in a CMS generation pass. + + Mechanical APDL Command: `EXBOPT `_ + + **Command default:** - APDL Command: EXBOPT + .. _EXBOPT_default: + + Default settings as described for each argument are used. Parameters ---------- - outinv2 + outinv2 : int or str Output control for 2nd order invariant: - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the second order invariant. + * ``0`` - Do not output (default). + + * ``1`` - Output the second order invariant. + + outtcms : int or str + Output control for :file:`.TCMS` file: + + * ``0`` - Do not output (default). - outtcms - Output control for .TCMS file: + * ``1`` - Output the :file:`.TCMS` file. - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the .TCMS file. + outsub : int or str + Output control for :file:`.SUB` file: - outsub - Output control for .SUB file: + * ``0`` - Do not output (default). - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the .SUB file. + * ``1`` - Output the :file:`.SUB` file. - OUTCMS - Output control for .CMS file: + outcms : int or str + Output control for :file:`.CMS` file: - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the .CMS file. + * ``0`` - Do not output (default). - outcomp + * ``1`` - Output the :file:`.CMS` file. + + outcomp : int or str Output control for node and element component information: - * ``"0"`` : Do not output any component information. - * ``"1"`` : Output node component information only. - * ``"2"`` : Output element component information only. - * ``"3"`` : Output both node and element component information (default). + * ``0`` - Do not output any component information. + + * ``1`` - Output node component information only. + + * ``2`` - Output element component information only. - outrm + * ``3`` - Output both node and element component information (default). + + outrm : int or str Output control for the recovery matrix: - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the recovery matrix to file.EXB. - * ``"2"`` : Output the recovery matrix to a separate file, file_RECOVER.EXB. + * ``0`` - Do not output (default). + + * ``1`` - Output the recovery matrix to :file:`fileEXB`. + + * ``2`` - Output the recovery matrix to a separate file, :file:`file_RECOVEREXB`. - noinv + noinv : int or str Invariant calculation: - * ``"0"`` : Calculate all invariants (default). - * ``"1"`` : Suppress calculation of the 1st and 2nd order - invariants. NOINV = 1 suppresses OUTINV2 = 1. + * ``0`` - Calculate all invariants (default). - OUTELE - Output control for the element data: + * ``1`` - Suppress calculation of the 1st and 2nd order invariants. NOINV = 1 suppresses OUTINV2 = + 1. - * ``"0"`` : Do not output (default). - * ``"1"`` : Output the element data. + outele : int or str + Output control for the element data: + + * ``0`` - Do not output (default). + + * ``1`` - Output the element data. Notes ----- - When the body property file (file.EXB) is requested in a CMS - generation pass (CMSOPT,,,,,,,EXB command), the .TCMS, .SUB, and - .CMS files are not output by default. Use the EXBOPT command to - request these files, as needed. - - EXBOPT can also be used to manage some content in the .EXB file - for improving performance and storage (see the OUTINV2, OUTCOMP, - OUTRM, NOINV, and OUTELE arguments described above). - - If both recovery matrix output (OUTRM = 1 or 2) and the .TCMS file - (OUTTCMS = 1) are requested, the .TCMS file writing is turned off - due to potentially large in-core memory use. - - For more information on how to generate file.EXB, see ANSYS - Interface to AVL EXCITE in the Mechanical APDL Substructuring - Analysis Guide + + .. _EXBOPT_notes: + + When the body property file ( :file:`file.EXB` ) is requested in a CMS generation pass ( + :ref:`cmsopt`,,,,,,,EXB command), the :file:`.TCMS`, :file:`.SUB`, and :file:`.CMS` files are not + output by default. Use the :ref:`exbopt` command to request these files, as needed. + + :ref:`exbopt` can also be used to manage some content in the :file:`.EXB` file for improving + performance and storage (see the ``OUTINV2``, ``OUTCOMP``, ``OUTRM``, ``NOINV``, and ``OUTELE`` + arguments described above). + + If both recovery matrix output ( ``OUTRM`` = 1 or 2) and the :file:`.TCMS` file ( ``OUTTCMS`` = 1) + are requested, the :file:`.TCMS` file writing is turned off due to potentially large in-core memory + use. + + For more information on how to generate :file:`file.EXB`, see `Ansys Interface to AVL EXCITE + `_ """ command = f"EXBOPT,{outinv2},{outtcms},{outsub},{outcms},{outcomp},{outrm},{noinv},{outele}" return self.run(command, **kwargs) - def ematwrite(self, key: str = "", **kwargs) -> Optional[str]: - """Forces the writing of all the element matrices to File.EMAT. + def expass(self, key: str = "", keystat: str = "", **kwargs): + r"""Specifies an expansion pass of an analysis. - APDL Command: EMATWRITE + Mechanical APDL Command: `EXPASS `_ Parameters ---------- - key - Write key: + key : str + Expansion pass key: + + * ``OFF`` - No expansion pass will be performed (default). - YES - Forces the writing of the element matrices to - File.EMAT even if not normally - done. + * ``ON`` - An expansion pass will be performed. - NO - Element matrices are written only if required. This - value is the default. + keystat : str + Static correction vectors key: + + * ``ON`` - Include static correction vectors in the expanded displacements (default). + + * ``OFF`` - Do not include static correction vectors in the expanded displacements. Notes ----- - The EMATWRITE command forces ANSYS to write the File.EMAT - file. The file is necessary if you intend to follow the - initial load step with a subsequent inertia relief - calculation (IRLF). If used in the solution - processor (/SOLU), this command is only valid within the - first load step. + + .. _EXPASS_notes: + + Specifies that an expansion pass of a modal, substructure, buckling, transient, or harmonic analysis + is to be performed. + + This separate solution pass requires an explicit :ref:`finish` from the preceding analysis and + reentry into SOLUTION. + + The ``KeyStat`` argument is applicable to the expansion pass of a substructure analysis, and to the + expansion pass of a component mode synthesis (CMS) analysis when the CMS method is fixed-interface + or free-interface. For a substructure analysis, the static correction vectors are the first terms of + in the `Mechanical APDL Theory Reference + `_. For a CMS + analysis, the static correction vectors are the third terms of. This command is also valid in PREP7. """ - command = f"EMATWRITE,{key}" + command = f"EXPASS,{key},,,{keystat}" return self.run(command, **kwargs) - def eqslv(self, lab="", toler="", mult="", keepfile="", **kwargs): - """Specifies the type of equation solver. + def gauge(self, opt: str = "", freq: int | str = "", **kwargs): + r"""Gauges the problem domain for a magnetic edge-element formulation. - APDL Command: EQSLV + Mechanical APDL Command: `GAUGE `_ Parameters ---------- - lab - Equation solver type: + opt : str + Type of gauging to be performed: + + * ``ON`` - Perform tree gauging of the edge values (default). + + * ``OFF`` - Gauging is off. (You must specify custom gauging via APDL specifications.) + + * ``STAT`` - Gauging status (returns the current ``Opt`` and ``FREQ`` values) + + freq : int or str + The following options are valid when ``Opt`` = ON: + + * ``0`` - Generate tree-gauging information once, at the first load step. Gauging data is retained + for subsequent load steps. (This behavior is the default.) + + * ``1`` - Repeat gauging for each load step. Rewrites the gauging information at each load step to + accommodate changing boundary conditions on the AZ degree of freedom (for example, adding or + deleting AZ constraints via the :ref:`d` or :ref:`ce` commands). + + Notes + ----- + + .. _GAUGE_notes: + + The :ref:`gauge` command controls the tree-gauging procedure required for electromagnetic analyses + using an edge-based magnetic formulation (elements ``SOLID226``, ``SOLID227``, ``SOLID236`` and + ``SOLID237`` ). + + Gauging occurs at the solver level for each solution ( :ref:`solve` ). It sets additional zero + constraints on the edge-flux degrees of freedom AZ to produce a unique solution; the additional + constraints are removed after solution. + + Use the ``FREQ`` option to specify how the command generates gauging information for multiple load + steps. + + Access the gauging information via the _TGAUGE component of gauged nodes. The program creates and + uses this component internally to remove and reapply the AZ constraints required by gauging. If + ``FREQ`` = 0, the _TGAUGE component is created at the first load step and is used to reapply the + tree gauge constraints at subsequent load steps. If ``FREQ`` = 1, the tree-gauging information and + the _TGAUGE component are generated at every load step + + If gauging is turned off ( :ref:`gauge`,OFF), you must specify your own gauging at the APDL level. - SPARSE - Sparse direct equation solver. Applicable to - real-value or complex-value symmetric and - unsymmetric matrices. Available only for STATIC, - HARMIC (full method only), TRANS (full method - only), SUBSTR, and PSD spectrum analysis types - [ANTYPE]. Can be used for nonlinear and linear - analyses, especially nonlinear analysis where - indefinite matrices are frequently - encountered. Well suited for contact analysis - where contact status alters the mesh - topology. Other typical well-suited applications - are: (a) models consisting of shell/beam or - shell/beam and solid elements (b) models with a - multi-branch structure, such as an automobile - exhaust or a turbine fan. This is an alternative - to iterative solvers since it combines both speed - and robustness. Generally, it requires - considerably more memory (~10x) than the PCG - solver to obtain optimal performance (running - totally in-core). When memory is limited, the - solver works partly in-core and out-of-core, - which can noticeably slow down the performance of - the solver. See the BCSOPTION command for more - details on the various modes of operation for - this solver. - - This solver can be run in shared memory parallel or - distributed memory parallel (Distributed ANSYS) mode. When - used in Distributed ANSYS, this solver preserves all of - the merits of the classic or shared memory sparse - solver. The total sum of memory (summed for all processes) - is usually higher than the shared memory sparse - solver. System configuration also affects the performance - of the distributed memory parallel solver. If enough - physical memory is available, running this solver in the - in-core memory mode achieves optimal performance. The - ideal configuration when using the out-of-core memory mode - is to use one processor per machine on multiple machines - (a cluster), spreading the I/O across the hard drives of - each machine, assuming that you are using a high-speed - network such as Infiniband to efficiently support all - communication across the multiple machines. - This solver - supports use of the GPU accelerator capability. - - JCG - Jacobi Conjugate Gradient iterative equation - solver. Available only for STATIC, HARMIC (full - method only), and TRANS (full method only) analysis - types [ANTYPE]. Can be used for structural, thermal, - and multiphysics applications. Applicable for - symmetric, unsymmetric, complex, definite, and - indefinite matrices. Recommended for 3-D harmonic - analyses in structural and multiphysics - applications. Efficient for heat transfer, - electromagnetics, piezoelectrics, and acoustic field - problems. - - This solver can be run in shared memory parallel or - distributed memory parallel (Distributed ANSYS) mode. When - used in Distributed ANSYS, in addition to the limitations - listed above, this solver only runs in a distributed - parallel fashion for STATIC and TRANS (full method) - analyses in which the stiffness is symmetric and only when - not using the fast thermal option (THOPT). Otherwise, this - solver runs in shared memory parallel mode inside - Distributed ANSYS. - This solver supports use of the GPU - accelerator capability. When using the GPU accelerator - capability, in addition to the limitations listed above, - this solver is available only for STATIC and TRANS (full - method) analyses where the stiffness is symmetric and does - not support the fast thermal option (THOPT). - - ICCG - Incomplete Cholesky Conjugate Gradient iterative - equation solver. Available for STATIC, HARMIC (full - method only), and TRANS (full method only) analysis - types [ANTYPE]. Can be used for structural, - thermal, and multiphysics applications, and for - symmetric, unsymmetric, complex, definite, and - indefinite matrices. The ICCG solver requires more - memory than the JCG solver, but is more robust than - the JCG solver for ill-conditioned matrices. - - This solver can only be run in shared memory parallel - mode. This is also true when the solver is used inside - Distributed ANSYS. - This solver does not support use of - the GPU accelerator capability. - - QMR - Quasi-Minimal Residual iterative equation - solver. Available for the HARMIC (full method only) - analysis type [ANTYPE]. Can be used for - high-frequency electromagnetic applications, and for - symmetric, complex, definite, and indefinite - matrices. The QMR solver is more stable than the - ICCG solver. - - This solver can only be run in shared memory parallel - mode. This is also true when the solver is used inside - Distributed ANSYS. - This solver does not support use of - the GPU accelerator capability. - - PCG - Preconditioned Conjugate Gradient iterative equation - solver (licensed from Computational Applications and - Systems Integration, Inc.). Requires less disk file - space than SPARSE and is faster for large - models. Useful for plates, shells, 3-D models, large - 2-D models, and other problems having symmetric, - sparse, definite or indefinite matrices for - nonlinear analysis. Requires twice as much memory - as JCG. Available only for analysis types [ANTYPE] - STATIC, TRANS (full method only), or MODAL (with PCG - Lanczos option only). Also available for the use - pass of substructure analyses (MATRIX50). The PCG - solver can robustly solve equations with constraint - equations (CE, CEINTF, CPINTF, and CERIG). With - this solver, you can use the MSAVE command to obtain - a considerable memory savings. - - The PCG solver can handle ill-conditioned problems by - using a higher level of difficulty (see - PCGOPT). Ill-conditioning arises from elements with high - aspect ratios, contact, and plasticity. - This solver can - be run in shared memory parallel or distributed memory - parallel (Distributed ANSYS) mode. When used in - Distributed ANSYS, this solver preserves all of the merits - of the classic or shared memory PCG solver. The total sum - of memory (summed for all processes) is about 30% more - than the shared memory PCG solver. - - toler - Iterative solver tolerance value. Used only with the - Jacobi Conjugate Gradient, Incomplete Cholesky Conjugate - Gradient, Pre- conditioned Conjugate Gradient, and - Quasi-Minimal Residual equation solvers. For the PCG - solver, the default is 1.0E-8. The value 1.0E-5 may be - acceptable in many situations. When using the PCG Lanczos - mode extraction method, the default solver tolerance value - is 1.0E-4. For the JCG and ICCG solvers with symmetric - matrices, the default is 1.0E-8. For the JCG and ICCG - solvers with unsymmetric matrices, and for the QMR solver, - the default is 1.0E-6. Iterations continue until the SRSS - norm of the residual is less than TOLER times the norm of - the applied load vector. For the PCG solver in the linear - static analysis case, 3 error norms are used. If one of - the error norms is smaller than TOLER, and the SRSS norm - of the residual is smaller than 1.0E-2, convergence is - assumed to have been reached. See Iterative Solver in the - Mechanical APDL Theory Reference for details. - - mult - Multiplier (defaults to 2.5 for nonlinear analyses; 1.0 - for linear analyses) used to control the maximum number of - iterations performed during convergence calculations. Used - only with the Pre- conditioned Conjugate Gradient equation - solver (PCG). The maximum number of iterations is equal to - the multiplier (MULT) times the number of degrees of - freedom (DOF). If MULT is input as a negative value, then - the maximum number of iterations is equal to abs(MULT). - Iterations continue until either the maximum number of - iterations or solution convergence has been reached. In - general, the default value for MULT is adequate for - reaching convergence. However, for ill-conditioned - matrices (that is, models containing elements with high - aspect ratios or material type discontinuities) the - multiplier may be used to increase the maximum number of - iterations used to achieve convergence. The recommended - range for the multiplier is 1.0 MULT 3.0. Normally, a - value greater than 3.0 adds no further benefit toward - convergence, and merely increases time requirements. If - the solution does not converge with 1.0 MULT 3.0, or in - less than 10,000 iterations, then convergence is highly - unlikely and further examination of the model is - recommended. Rather than increasing the default value of - MULT, consider increasing the level of difficulty - (Lev_Diff) on the PCGOPT command. - - keepfile - Determines whether files from a SPARSE solver run should be deleted - or retained. Applies only to Lab = SPARSE for static and full - transient analyses. + This command is also valid in PREP7. """ - return self.run(f"EQSLV,{lab},{toler},{mult},,{keepfile}", **kwargs) + command = f"GAUGE,{opt},{freq}" + return self.run(command, **kwargs) - def eresx(self, key="", **kwargs): - """Specifies extrapolation of integration point results. + def gmatrix( + self, + symfac: str = "", + condname: str = "", + numcond: str = "", + matrixname: str = "", + **kwargs, + ): + r"""Performs electric field solutions and calculates the self and mutual conductance between multiple + conductors. - APDL Command: ERESX + Mechanical APDL Command: `GMATRIX `_ Parameters ---------- - key - Extrapolation key: + symfac : str + Geometric symmetry factor. Conductance values are scaled by this factor which represents the + fraction of the total device modeled. Defaults to 1. - DEFA - If element is fully elastic (no active plasticity, creep, or swelling - nonlinearities), extrapolate the integration point results - to the nodes. If any portion of the element is plastic (or - other active material nonlinearity), copy the integration - point results to the nodes (default). + condname : str + Alphanumeric prefix identifier used in defining named conductor components. - YES - Extrapolate the linear portion of the integration point results to the nodes - and copy the nonlinear portion (for example, plastic - strains). + numcond : str + Total number of components. If a ground is modeled, it is to be included as a component. - NO - Copy the integration point results to the nodes. + matrixname : str + Array name for computed conductance matrix. Defaults to GMATRIX. Notes ----- - Specifies whether the solution results at the element integration - points are extrapolated or copied to the nodes for element and nodal - postprocessing. The structural stresses, elastic and thermal strains, - field gradients, and fluxes are affected. Nonlinear data (plastic, - creep, and swelling strains) are always copied to the nodes, never - extrapolated. For shell elements, ERESX applies only to integration - point results in the in-plane directions. + To invoke the :ref:`gmatrix` macro, the exterior nodes of each conductor must be grouped into + individual components using the :ref:`cm` command. Each set of independent components is assigned a + component name with a common prefix followed by the conductor number. A conductor system with a + ground must also include the ground nodes as a component. The ground component is numbered last in + the component name sequence. - This command is also valid in PREP7. + A ground conductance matrix relates current to a voltage vector. A ground matrix cannot be applied + to a circuit modeler. The lumped conductance matrix is a combination of lumped "arrangements" of + voltage differences between conductors. Use the lumped conductance terms in a circuit modeler to + represent conductances between conductors. + + Enclose all name-strings in single quotes in the :ref:`gmatrix` command line. + + :ref:`gmatrix` works with the following elements: + + * ``SOLID5`` (KEYOPT(1) = 9) + + * ``SOLID98`` (KEYOPT(1) = 9) + + * ``LINK68`` + + * ``PLANE230`` + + * ``SOLID231`` + + * ``SOLID232`` + + This command is available from the menu path shown below only if existing results are available. + + This command does not support multiframe restarts Distributed-Memory Parallel (DMP) Restriction This + command is not supported in a DMP solution. """ - command = f"ERESX,{key}" + command = f"GMATRIX,{symfac},{condname},{numcond},,{matrixname}" return self.run(command, **kwargs) - def escheck( - self, sele: str = "", levl: str = "", defkey: MapdlInt = "", **kwargs - ) -> Optional[str]: - """Perform element shape checking for a selected element set. + def invopt(self, option: str = "", **kwargs): + r"""Enables or disables inverse solving for the current load step. - APDL Command: ESCHECK + Mechanical APDL Command: `INVOPT `_ Parameters ---------- - sele - Specifies whether to select elements for checking: + option : str + Enables or disables inverse solving for a load step: + + * ``ON`` - Enable. + + * ``OFF`` - Disable and revert to forward solving (default). + + Notes + ----- - (blank) - List all warnings/errors from element shape - checking. + .. _INVOPT_notes: - ESEL - Select the elements based on the .Levl criteria - specified below. + ``Option`` = ON is valid only at the first load step of a static analysis. Large-deflection effects + must be enabled ( :ref:`nlgeom`,ON). The unsymmetric solver ( :ref:`nropt`,UNSYM) is required and + the program selects it automatically. - levl - WARN - Select elements producing warning and error messages. + After issuing :ref:`invopt`,ON, inverse solving remains in effect until :ref:`invopt`,OFF is + issued. The solution then reverts to traditional forward solving (default). - ERR - Select only elements producing error messages ( - default). + This command cannot be issued during a restart. ``Option`` can only be changed between load steps. - defkey - Specifies whether check should be performed on deformed - element - shapes. . + For more information, see `Nonlinear Static Analysis with Inverse Solving + `_ + """ + command = f"INVOPT,{option}" + return self.run(command, **kwargs) + + def lanboption( + self, strmck: str = "", altmeth: str = "", memory_option: str = "", **kwargs + ): + r"""Specifies Block Lanczos eigensolver options. - 0 - Do not update node coordinates before performing - shape checks (default). + Mechanical APDL Command: `LANBOPTION `_ + + Parameters + ---------- + strmck : str + Controls whether the Block Lanczos eigensolver will perform a Sturm sequence check: - 1 - Update node coordinates using the current set of - deformations in the database. + * ``OFF`` - Do not perform the Sturm sequence check (default). + + * ``ON`` - Perform a Sturm sequence check. This requires additional matrix factorization (which can + be expensive), but does help ensure that no modes are missed in the specified range. + + altmeth : str + + * ``ALT1`` - Alternative version of the Block Lanczos eigensolver for more difficult modal or + buckling problems. This version of Block Lanczos only runs in shared-memory parallel (SMP) mode. If + the analysis is run in distributed-memory parallel (DMP) mode, it will switch to SMP mode when this + Alternative Block Lanczos solver is invoked, and resume in DMP mode after the eigensolution. + + memory_option : str + Memory allocation option: + + * ``DEFAULT`` - Default memory configuration (default). Everything is determined dynamically with + respect to current machine resources. + + * ``INCORE`` - Fully in-core memory configuration. + + * ``MIX1`` - First level of mixed in-core / out-of-core configuration. + + * ``MIX2`` - Second level of mixed in-core / out-of-core configuration. + + * ``OUTOFCORE`` - Fully out-of-core memory configuration. Notes ----- - Shape checking will occur according to the current SHPP - settings. Although ESCHECK is valid in all processors, - Defkey uses the current results in the database. If no - results are available a warning will be issued. - This command is also valid in PREP7, SOLUTION and POST1. + .. _LANBOPTION_notes: + + :ref:`lanboption` specifies options to be used with the Block Lanczos eigensolver during an + eigenvalue buckling analysis ( :ref:`bucopt`,LANB) or a modal analysis ( :ref:`modopt`,LANB). + + For more difficult eigenproblems, ``AltMeth`` = ALT1 could achieve better converged eigensolutions + at the cost of more computing time. This ALT1 option is useful for double-checking solution + accuracy. It should be used for difficult eigenproblems like those with many duplicated eigenmodes, + or eigen-buckling problems with very thin beam/shell structures. + + **Memory Allocation Option** + + The Block Lanczos eigensolver algorithm allocates two main pools of memory: + + Memory for the internal sparse solver iterations. + + Memory for the specific Lanczos working arrays. + + The following table shows how memory is allocated for each option. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + The MIX1 configuration typically uses more memory than the MIX2 configuration, except when a large + number of modes are requested for a small model. """ - command = f"ESCHECK,{sele},{levl},{defkey}" + command = f"LANBOPTION,{strmck},,{altmeth},{memory_option}" return self.run(command, **kwargs) - def essolv( - self, - electit="", - strutit="", - dimn="", - morphopt="", - mcomp="", - xcomp="", - electol="", - strutol="", - mxloop="", - ruseky="", - restky="", - eiscomp="", - **kwargs, - ): - """Performs a coupled electrostatic-structural analysis. + def lumpm(self, key: str = "", keyelt: int | str = "", **kwargs): + r"""Specifies a lumped mass matrix formulation. + + Mechanical APDL Command: `LUMPM `_ + + Parameters + ---------- + key : str + Formulation key: + + * ``OFF`` - Use the element-dependent default mass matrix formulation (default). + + * ``ON`` - Use a lumped mass approximation. + + keyelt : int or str + Formulation key for elements with rotational degrees of freedom; applicable only when the lumped + mass formulation key is turned on ( ``Key`` = ON): + + * ``0 (blank)`` - Use direct diagonalization of the element mass matrix (default). + + * ``1`` - Use translational mass only. + + * ``2`` - Use the frame invariant formulation. + + Notes + ----- + + .. _LUMPM_notes: + + In a modal analysis, the lumped mass matrix option ( :ref:`lumpm`,ON) is not allowed when using the + Supernode mode-extraction method ( :ref:`modopt`,SNODE). The eigensolver will automatically be + switched to Block Lanczos (LANB) in this case. + + In the use pass of a substructuring analysis, the lumped mass matrix formulation ( :ref:`lumpm`,ON) + modifies the superelement mass matrix and may give unexpected results. + + The translational mass only option ( :ref:`lumpm`,ON,,1) applies to the following elements: + ``SHELL181``, ``BEAM188``, ``BEAM189``, ``SHELL208``, ``SHELL209``, ``SHELL281``, ``PIPE288``, + ``PIPE289``, and ``ELBOW290``. The frame invariant formulation ( :ref:`lumpm`,ON,,2) applies only to + ``BEAM188``, ``BEAM189``, ``PIPE288``, and ``PIPE289`` elements. - APDL Command: ESSOLV + For more information, see `Lumped Matrices + `_ + + This command is also valid in PREP7. If used in SOLUTION, this command is valid only within the + first load step. + """ + command = f"LUMPM,{key},,{keyelt}" + return self.run(command, **kwargs) + + def moddir(self, key: str = "", directory: str = "", fname: str = "", **kwargs): + r"""Enables remote read-only usage of modal analysis files or substructuring analysis files. + + Mechanical APDL Command: `MODDIR `_ Parameters ---------- - electit - Title of the electrostatics physics file as assigned by the PHYSICS - command. + key : str + Key for enabling remote read-only usage of modal analysis files or `substructuring + `_ analysis files: + + * ``1 (ON or YES)`` - The program performs the analysis using remote files. The files are read-only. - strutit - Title of the structural physics file as assigned by the PHYSICS - command. + * ``0 (OFF or NO)`` - The program performs the analysis using files located in the working directory + (default). + + * ``LIST`` - List remote modal files status, directory path, and file name. + + directory : str + Directory path (248 characters maximum). The directory contains the modal analysis files or the + substructuring generation pass files. + + The directory path defaults to the current working directory. - dimn - Model dimensionality (a default is not allowed): + fname : str + File name (no extension or directory path) for the modal analysis files or the substructuring + generation pass files. - 2 - 2-D model. + The file name defaults to the current :file:`Jobname`. + + Notes + ----- - 3 - 3-D model. + .. _MODDIR_notes: - morphopt - Morphing option: + This commands is used when solving linked analyses in two different folders. It is mostly meant to + be used to reduce solution time and disk space usage by specifying the path to required solution + files rather than copying them in the Mechanical Application (see the file management sections of + the following + analyses: mode-superposition transient, mode-superposition harmonic, response spectrum, random + vibration, and substructure generation in the Mechanical User's Guide ). - <0 - Do not perform any mesh morphing or remeshing. + This command applies to the following analysis types: - 0 - Remesh the non-structural regions for each recursive loop only if mesh morphing - fails (default). + * Spectrum ( :ref:`antype`,SPECTR) - 1 - Remesh the non-structural regions each recursive loop and bypass mesh morphing. + * Modal restart ( :ref:`antype`, MODAL, RESTART) - 2 - Perform mesh morphing only, do not remesh any non-structural regions. + * Mode-superposition transient ( :ref:`antype`,TRANS and :ref:`trnopt`, MSUP) - mcomp - Component name of the region to be morphed. For 2-D models, the - component may be elements or areas. For 3-D models, the component - may be elements or volumes. A component must be specified. You - must enclose name-strings in single quotes in the ESSOLV command - line. + * Mode-superposition harmonic ( :ref:`antype`,HARM and :ref:`hropt`, MSUP) - xcomp - Component name of entities excluded from morphing. In the 2-D - case, it is the component name for the lines excluded from - morphing. In the 3-D case, it is component name for the areas - excluded from morphing. Defaults to exterior non-shared entities - (see the DAMORPH, DVMORPH, and DEMORPH commands). You must enclose - name-strings in single quotes in the ESSOLV command line. + * Substructuring ( :ref:`antype`,SUBSTR). - electol - Electrostatic energy convergence tolerance. Defaults to .005 (.5%) - of the value computed from the previous iteration. If less than - zero, the convergence criteria based on electrostatics results is - turned off. + Using the default for both the directory path ( ``Directory`` ) and the file name ( ``Fname`` ) is + not valid. At least one of these values must be specified. - strutol - Structural maximum displacement convergence tolerance. Defaults to - .005 (.5%) of the value computed from the previous iteration. If - less than zero, the convergence criteria base on structural results - is turned off. + In a spectrum analysis and in mode-superposition analyses, :ref:`moddir` must be issued during the + first solution and at the beginning of the solution phase (before :ref:`lvscale` in particular). In + a spectrum analysis, remote modal files usage is not supported when mode file reuse is activated ( + ``modeReuseKey`` = YES on :ref:`spopt` ). - mxloop - Maximum number of allowable solution recursive loops. A single - pass through both an electrostatics and structural analysis - constitutes one loop. Defaults to 100. + After a `PSD spectrum analysis + `_, + :ref:`moddir` can be issued in POST26 prior to the :ref:`store` command. - ruseky - Reuse flag option: + In a modal restart analysis, :ref:`moddir` must be issued during the first solution. Remote modal + files usage cannot be activated in a modal restart analysis if during the first modal analysis: - 1 - Assumes initial run of ESSOLV using base geometry for - the first electrostatics solution. + * Enforced static modes have been calculated ( ``EnforcedKey`` = ON on :ref:`modcont` ). - >1 - Assumes ESSOLV run is a continuation of a previous - ESSOLV run, whereby the morphed geometry is used for - the initial electrostatic simulation. + * Element result superposition key ( ``MSUPkey`` on :ref:`mxpand` ) was set to NO, whereas it is set + to YES in the modal restart. - restky - Structural restart key. + When using distributed-memory parallel processing, if element results calculation based on element + modal results is activated for the spectrum analysis ( ``Elcalc`` = YES on :ref:`spopt` ), + :ref:`moddir` usage can significantly reduce computation time as it decreases the size of the + distributed :file:`.rst` files to be combined at the end of spectrum analysis solution. - 0 - Use static solution option for structural solution. + In a substructuring or CMS analysis, :ref:`moddir` can be issued during either of the following + analysis phases: - 1 - Use static restart solution option for structural solution. + * The first solution of the first restart of a generation pass. ``ExpMth`` on :ref:`seopt` must be + set to MODDIR during the first solve of the primary generation pass. - eiscomp - Element component name for elements containing initial stress data - residing in file jobname.ist. The initial stress data must be - defined prior to issuing ESSOLV (see INISTATE command). + * The first solution of the expansion pass. + + """ + command = f"MODDIR,{key},{directory},{fname}" + return self.run(command, **kwargs) + + def monitor(self, var: str = "", node: str = "", lab: str = "", **kwargs): + r"""Controls contents of variable fields in the nonlinear solution monitor file. + + Mechanical APDL Command: `MONITOR `_ + + Parameters + ---------- + var : str + One of four variable field numbers in the monitor file whose contents can be specified by the + Lab field. Valid arguments are integers 1, 2, 3, or 4. See Notes section for default values. + + node : str + The node number for which information is monitored in the specified ``VAR`` field. In the GUI, + if ``Node`` = P, graphical picking is enabled. If blank, the monitor file lists the maximum + value of the specified quantity (Lab field) for the entire structure. + + lab : str + The solution quantity to be monitored in the specified ``VAR`` field. Valid labels for solution + quantities are UX, UY, and UZ (displacements); ROTX, ROTY, and ROTZ (rotations); and TEMP + (temperature). Valid labels for reaction force are FX, FY, and FZ (structural force) and MX, MY, + and MZ (structural moment). Valid label for heat flow rate is HEAT. For defaults see the Notes + section. Notes ----- - ESSOLV invokes an ANSYS macro which automatically performs a coupled - electrostatic-structural analysis. - - The macro displays periodic updates of the convergence. - - If non-structural regions are remeshed during the analysis, boundary - conditions and loads applied to nodes and elements will be lost. - Accordingly, it is better to assign boundary conditions and loads to - the solid model. - - Use RUSEKY > 1 for solving multiple ESSOLV simulations for different - excitation levels (i.e., for running a voltage sweep). Do not issue the - SAVE command to save the database between ESSOLV calls. - - For nonlinear structural solutions, the structural restart option - (RESTKY = 1) may improve solution time by starting from the previous - converged structural solution. - - For solid elements, ESSOLV automatically detects the air-structure - interface and applies a Maxwell surface flag on the electrostatic - elements. This flag is used to initiate the transfer for forces from - the electrostatic region to the structure. When using the ESSOLV - command with structural shell elements (for example, SHELL181), you - must manually apply the Maxwell surface flag on all air elements - surrounding the shells before writing the final electrostatic physics - file. Use the SFA command to apply the Maxwell surface flag to the - areas representing the shell elements; doing so ensures that the air - elements next to both sides of the shells receive the Maxwell surface - flag. - - If lower-order structural solids or shells are used, set KEYOPT(7) = 1 - for the electrostatic element types to ensure the correct transfer of - forces. - - Information on creating the initial stress file is documented in the - Loading chapter in the Basic Analysis Guide. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + + .. _MONITOR_notes: + + The monitor file always has an extension of **.mntr**, and takes its file name from the specified + :file:`Jobname`. If no :file:`Jobname` is specified, the file name defaults to :file:`file`. + + You must issue this command once for each solution quantity you want to monitor at a specified node + at each load step. You cannot monitor a reaction force during a linear analysis. The variable field + contents can be redefined at each load step by reissuing the command. The monitored quantities are + appended to the file for each load step. + + Reaction forces reported in the monitor file may be incorrect if the degree of freedom of the + specified node is involved in externally defined coupling ( :ref:`cp` command) or constraint + equations ( :ref:`ce` command), or if the program has applied constraint equations internally to the + node. + + The following example shows the format of a monitor file. Note that the file only records the + solution substep history when a substep is convergent. + + _font TypeSize="8pt"? SOLUTION HISTORY INFORMATION FOR JOB: file.mntr LOAD SUB- NO. NO. TOTL + INCREMENT TOTAL VARIAB 1 + VARIAB 2 VARIAB 3 VARIAB 4 STEP STEP ATTMP ITER ITER TIME/LFACT TIME/LFACT MONITOR MONITOR MONITOR + MONITOR Wall MxDs FY MxRe 1 1 1 5 5 0.36000E-01 0.36000E-01 0.0000 -0.47242E-01 -0.13783E-01 + 0.22670E-04 1 2 1 3 8 0.36000E-01 0.72000E-01 0.0000 -0.91552E-01 -0.27269E-01 0.38849E-03 1 3 1 4 + 12 0.54000E-01 0.12600 0.0000 -0.15161 -0.43972E-01 0.25235E-03 1 4 1 3 15 0.81000E-01 0.20700 + 0.0000 -0.22926 -0.65119E-01 0.11131E-03 1 5 1 5 20 0.12150 0.32850 0.0000 -0.34188 -0.93242E-01 + 0.12267E-02 1 6 1 4 24 0.12150 0.45000 0.0000 -0.46860 -0.11992 0.22689E-02 1 7 1 5 29 0.18000 + 0.63000 0.0000 -0.65720 -0.16217 0.12111E-03 1 8 2 7 38 0.63000E-01 0.69300 0.0000 -0.72594 -0.46582 + 0.67121E-02 1 9 1 11 49 0.63000E-01 0.75600 0.0000 -0.79976 -1.1070 0.29302E-02 1 10 1 10 59 + 0.63000E-01 0.81900 0.0000 -0.87073 -1.8708 0.95828E-02 1 11 1 18 77 0.81000E-01 0.90000 0.0000 + -0.90000 -269.31 0.73911/_font? + The following details the contents of the various fields in the monitor file: + + * ``LOAD STEP`` - The current load step number. + + * ``SUBSTEP`` - The current substep (time step) number. + + * ``NO. ATTEMPT`` - The number of attempts made in solving the current substep. This number is equal + to the number of failed attempts (bisections) plus one (the successful attempt). + + * ``NO. ITER`` - The number of iterations used by the last successful attempt. + + * ``TOTL. ITER`` - Total cumulative number of iterations (including each iteration used by a + bisection). + + * ``INCREMENT`` - + + * ``TIME/LFACT`` - Time or load factor increments for the current substep. + + * ``TOTAL TIME/LFACT`` - Total time (or load factor) for the last successful attempt in the current + substep. + + * ``VARIAB 1`` - Variable field 1. By default, this field lists the elapsed (or wall clock) times + used up to (but not including) the current substep. + + * ``VARIAB 2`` - Variable field 2. In this example, the field is reporting the MZ value. By default, + this field lists the maximum displacement in the entire structure. + + * ``VARIAB 3`` - Variable field 3. In this example, the field is reporting the FY value of a certain + node. By default, this field reports the maximum equivalent plastic strain increment in the entire + structure. + + * ``VARIAB 4`` - Variable field 4. By default, this field reports the maximum residual force in the + entire structure. """ - command = f"ESSOLV,{electit},{strutit},{dimn},{morphopt},{mcomp},{xcomp},{electol},{strutol},{mxloop},,{ruseky},{restky},{eiscomp}" + command = f"MONITOR,{var},{node},{lab}" return self.run(command, **kwargs) - def expass(self, key="", keystat="", **kwargs): - """Specifies an expansion pass of an analysis. + def msave(self, key: str = "", **kwargs): + r"""Sets the solver memory saving option. This option only applies to the PCG solver (including PCG + Lanczos). - APDL Command: EXPASS + Mechanical APDL Command: `MSAVE `_ Parameters ---------- - key - Expansion pass key: - * OFF - No expansion pass will be performed (default). - * ON - An expansion pass will be performed. + key : str + Activation key: + + * ``0 or OFF`` - Use global assembly for the stiffness matrix (and mass matrix, when using PCG + Lanczos) of the entire model. + + * ``1 or ON`` - Use an element-by-element approach when possible to save memory during the solution. + In this case, the global stiffness (and mass) matrix is not assembled; element stiffness (and mass) + is regenerated during PCG or PCG Lanczos iterations. + + Notes + ----- + + .. _MSAVE_notes: + + :ref:`msave`,ON only applies to and is the default for parts of the model using the following + element types with linear material properties that meet the conditions listed below. + + * ``SOLID186`` (Structural Solid only) + + * ``SOLID187`` + + The following conditions must also be true: - keystat - Static correction vectors key: - * ON - Include static correction vectors in the expanded displacements (default). - * OFF - Do not include static correction vectors in the expanded displacements. + * The PCG solver has been specified. - Notes - ----- - Specifies that an expansion pass of a modal, substructure, buckling, - transient, or harmonic analysis is to be performed. + * Small strains are assumed ( :ref:`nlgeom`,OFF). - Note:: : This separate solution pass requires an explicit FINISH to - preceding analysis and reentry into SOLUTION. + * No prestress effects ( :ref:`pstres` ) are included. - This command is also valid in PREP7. - """ - command = f"EXPASS,{key},,,{keystat}" - return self.run(command, **kwargs) + * All nodes on the supported element types must be defined (that is, the midside nodes cannot be + removed using the :ref:`emid` command). - def gauge(self, opt="", freq="", **kwargs): - """Gauges the problem domain for a magnetic edge-element formulation. + * For elements with thermally dependent material properties, :ref:`msave`,ON applies only to + elements with uniform temperatures prescribed. - APDL Command: GAUGE + * The default element coordinate system must be used. - Parameters - ---------- - opt - Type of gauging to be performed: + If you manually force :ref:`msave`,ON by including it in the input file, the model can include the + following additional conditions: - ON - Perform tree gauging of the edge values (default). + * The analysis can be a modal analysis using the PCG Lanczos method ( :ref:`modopt`,LANPCG). - OFF - Gauging is off. (You must specify custom gauging via APDL specifications.) + * Large deflection effects ( :ref:`nlgeom`,ON) can be included for ``SOLID186`` and/or ``SOLID187`` + elements. - STAT - Gauging status (returns the current Opt and FREQ values) + * ``SOLID185`` (brick shapes and KEYOPT(2) = 3 only) elements can be included for small strains ( + :ref:`nlgeom`,OFF). - freq - The following options are valid when Opt = ON: + All other element types or other parts of the model that don't meet the above criteria will be + solved using global assembly ( :ref:`msave`,OFF). This command can result in memory savings of up to + 70 percent over the global assembly approach for the part of the model that meets the criteria. + Depending on the hardware (for example, processor speed, memory bandwidth, etc.), the solution time + may increase or decrease when this feature is used. - 0 - Generate tree-gauging information once, at the first load step. Gauging data is - retained for subsequent load steps. (This behavior is the - default.) + This memory-saving feature runs in parallel when multiple processors are used with the :ref:`config` + command or in a distributed-memory parallel (DMP) solution. The gain in performance with using + multiple processors with this feature turned on should be similar to the default case when this + feature is turned off. Performance also improves when using the uniform reduced integration option + for ``SOLID186`` elements. - 1 - Repeat gauging for each load step. Rewrites the gauging information at each - load step to accommodate changing boundary conditions on the AZ - degree of freedom (for example, adding or deleting AZ - constraints via the D or CE commands). + This command does not support the layered option of the SOLID185 and ``SOLID186`` elements. - Notes - ----- - The GAUGE command controls the tree-gauging procedure required for - electromagnetic analyses using an edge-based magnetic formulation - (elements SOLID236 and SOLID237). + When using :ref:`msave`,ON with the :ref:`pcgopt` command, note the following restrictions: - Gauging occurs at the solver level for each solution (SOLVE). It sets - additional zero constraints on the edge-flux degrees of freedom AZ to - produce a unique solution; the additional constraints are removed after - solution. + * For static and modal analyses, :ref:`msave`,ON is not valid when using a ``Lev_Diff`` value of 5 + on the :ref:`pcgopt` command; ``Lev_Diff`` is automatically reset to 2. - Use the FREQ option to specify how the command generates gauging - information for multiple load steps. + * For modal analyses, :ref:`msave`,ON is not valid with the ``StrmCk`` option of the :ref:`pcgopt` + command; ``Strmck`` is set to OFF. - Access the gauging information via the _TGAUGE component of gauged - nodes. The program creates and uses this component internally to remove - and reapply the AZ constraints required by gauging. If FREQ = 0, the - _TGAUGE component is created at the first load step and is used to - reapply the tree gauge constraints at subsequent load steps. If FREQ = - 1, the tree-gauging information and the _TGAUGE component are generated - at every load step + * For all analysis types, :ref:`msave`,ON is not valid when the Lagrange multiplier option ( + ``LM_Key`` ) of the :ref:`pcgopt` command is set to ON; the :ref:`msave` activation key is set to + OFF. - If gauging is turned off (GAUGE,OFF), you must specify your own gauging - at the APDL level. + * For linear perturbation static and modal analyses, :ref:`msave`,ON is not valid; the :ref:`msave` + activation key is set to OFF. - This command is also valid in PREP7. + * For static analyses, :ref:`msave`,ON is not valid when the ``Fallback`` option of the + :ref:`pcgopt` command is enabled; ``Fallback`` is automatically reset to OFF. + + When using :ref:`msave`,ON for modal analyses, no :file:`.FULL` file will be created. The + :file:`.FULL` file may be necessary for subsequent analyses (for example, harmonic, transient mode- + superposition, or spectrum analyses). To generate the :file:`.FULL` file, rerun the modal analysis + using the :ref:`wrfull` command. """ - command = f"GAUGE,{opt},{freq}" + command = f"MSAVE,{key}" return self.run(command, **kwargs) - def gmatrix(self, symfac="", condname="", numcond="", matrixname="", **kwargs): - """Performs electric field solutions and calculates the self and mutual + def msolve( + self, + numslv: str = "", + val1: str = "", + val2: str = "", + lab: str = "", + angfix: str = "", + **kwargs, + ): + r"""Starts multiple solutions for an acoustic analysis. - APDL Command: GMATRIX - conductance between multiple conductors. + Mechanical APDL Command: `MSOLVE `_ Parameters ---------- - symfac - Geometric symmetry factor. Conductance values are scaled by this - factor which represents the fraction of the total device modeled. - Defaults to 1. + numslv : str + Number of multiple solutions (load steps). This number corresponds to the number of random + samplings for the diffuse sound field in a random acoustic analysis, or the incident angles of + the plane wave when the Floquet periodic boundary condition is present. Default = 1. - condname - Alphanumeric prefix identifier used in defining named conductor - components. + val1 : str + The meaning of ``VAL1`` depends on the ``Lab`` value. - numcond - Total number of components. If a ground is modeled, it is to be - included as a component. + For ``Lab`` = DSF, ``VAL1`` is the norm convergence tolerance defined by comparing the averaged + radiated diffuse sound power of two multiple sampling sets over the frequency range for the + diffuse sound field (default = 0.05). - matrixname - Array name for computed conductance matrix. Defaults to GMATRIX. + For ``Lab`` = APHI or ATHETA, ``VAL1`` is the beginning angle for the incident angle sweep of + the plane wave (default = 0). - Notes - ----- - To invoke the GMATRIX macro, the exterior nodes of each conductor must - be grouped into individual components using the CM command. Each set - of independent components is assigned a component name with a common - prefix followed by the conductor number. A conductor system with a - ground must also include the ground nodes as a component. The ground - component is numbered last in the component name sequence. - - A ground conductance matrix relates current to a voltage vector. A - ground matrix cannot be applied to a circuit modeler. The lumped - conductance matrix is a combination of lumped "arrangements" of - voltage differences between conductors. Use the lumped conductance - terms in a circuit modeler to represent conductances between - conductors. + val2 : str + The meaning of ``VAL2`` depends on the ``Lab`` value. + + For ``Lab`` = DSF, ``VAL2`` is the interval of the norm convergence check for the diffuse sound + field (default = 5). - Enclose all name-strings in single quotes in the GMATRIX command line. + For ``Lab`` = APHI or ATHETA, ``VAL2`` is the ending angle for the incident angle sweep of the + plane wave (default = 0). - GMATRIX works with the following elements: + lab : str + Label indicating the type of acoustic analysis: - SOLID5 (KEYOPT(1) = 9) + * ``DSF`` - Diffuse sound field with multiple solutions (default). - SOLID98 (KEYOPT(1) = 9) + * ``APHI`` - Plane wave angle sweep with fixed :math:`equation not available` angle and varied + :math:`equation not available` angle (see the :ref:`aport` command). - LINK68 + * ``ATHETA`` - Plane wave angle sweep with fixed :math:`equation not available` angle and varied + :math:`equation not available` angle (see the :ref:`aport` command). - PLANE230 + angfix : str + The value of the fixed incident angle for the plane wave angle sweep (used only when ``Lab`` = + APHI or ATHETA). - SOLID231 + Notes + ----- + The :ref:`msolve` command starts multiple solutions (load steps) for a random acoustic analysis with + multiple samplings or for the angle sweep of the incident plane wave with the Floquet periodic + boundary condition, as described below. + + **Random Acoustic Analysis (** ``Lab`` = DSF) + + Use ``Lab`` = DSF for a random acoustic analysis. The process is controlled by the norm convergence + tolerance ( ``VAL1`` ) or the number of multiple solutions ( ``NUMSLV`` ) if the solution steps + reach the defined number. - SOLID232 + The program checks the norm convergence by comparing two averaged sets of radiated sound powers with + the interval ``VAL2`` over the frequency range. For example, if ``VAL2`` = 5, the averaged values + from 5 solutions are compared with the averaged values from 10 solutions, then the averaged values + from 10 solutions are compared with the averaged values from 15 solutions, and so on. - This command is available from the menu path shown below only if - existing results are available. + The incident diffuse sound field is defined via the :ref:`dfswave` command. - This command does not support multiframe restarts + The average result of multiple solutions with different samplings is calculated via the :ref:`pras` + or :ref:`plas` command. - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + **Plane Wave Incident Angle Sweep (** ``Lab`` = APHI or ATHETA) + + Use ``Lab`` = APHI or ATHETA to perform an angle sweep for the incident plane wave defined by the + :ref:`aport` command. The process is controlled by the number of multiple solutions ( ``NUMSLV`` ). + The plane wave port must be defined with the default values of incident angles prior to the + :ref:`msolve` command. + + The sound power parameters are calculated over the sweeping angles during postprocessing by the + :ref:`pras` or :ref:`plas` command. """ - command = f"GMATRIX,{symfac},{condname},{numcond},,{matrixname}" + command = f"MSOLVE,{numslv},{val1},{val2},{lab},{angfix}" return self.run(command, **kwargs) - def invopt(self, option="", **kwargs): - """Enables or disables inverse solving for the current load step. + def opncontrol(self, lab: str = "", value: str = "", numstep: str = "", **kwargs): + r"""Sets decision parameter for automatically increasing the time step interval in a pure thermal + analysis. - APDL Command: INVOPT + Mechanical APDL Command: `OPNCONTROL `_ Parameters ---------- - Option - Enables or disables inverse solving for a load step: - - ON - Enable. - OFF - Disable and revert to forward solving (default). + lab : str + * ``TEMP`` - Degree-of-freedom label used to base a decision for increasing the time step (substep) + interval in a nonlinear or transient analysis. The only DOF label currently supported is TEMP. - Notes - ----- - Option = ON is valid only at the first load step of a static analysis. - Large-deflection effects must be enabled (NLGEOM,ON). - The unsymmetric solver (NROPT,UNSYM) is required and the program selects - it automatically. + * ``OPENUPFACTOR`` - Key to set a multiplier for increasing the time step interval as specified in ``VALUE`` > 1.0 (up to + 10.0). Valid only when :ref:`autots`,ON has been issued. - After issuing INVOPT,ON, inverse solving remains in effect - until INVOPT,OFF is issued. - The solution then reverts to traditional forward solving (default). + The multiplier is set by issuing :ref:`opncontrol`,OPENUPFACTOR, ``VALUE`` as follows: - This command cannot be issued during a restart. Option can only be - changed between load steps. + * For a pure thermal analysis, if ``VALUE`` > 1.0, the OPENUPFACTOR is the minimum of 10.0, + ``VALUE``. - For more information, see Nonlinear Static Analysis with Inverse Solving - in the Structural Analysis Guide. - """ - return self.run(f"INVOPT,{option}", **kwargs) + If the user does not specify the multiplier, the default is 3.0. - def lanboption(self, strmck="", **kwargs): - """Specifies Block Lanczos eigensolver options. + Generally, ``VALUE`` > 3.0 is not recommended. Note that in some rare cases this specification can + be overwritten by internal heuristics in determining the new time step interval. - APDL Command: LANBOPTION + value : str + A context sensitive value that depends on ``Lab`` : - Parameters - ---------- - strmck - Controls whether the Block Lanczos eigensolver will perform a - Sturm sequence check: + * If ``Lab`` = TEMP, ``VALUE`` is used together with ``NUMSTEP`` in the algorithm for determining if + the time step interval can be increased. The time step interval is increased if the maximum + absolute value of the incremental solution is less than ``VALUE`` for the number of contiguous + time steps specified by ``NUMSTEP`` (default ``VALUE`` = 0.1). - * ``"OFF"`` : Do not perform the Sturm sequence check - (default). + * If ``Lab`` = OPENUPFACTOR, ``VALUE`` is a multiplier (= 1.0 - 10.0) that can be specified for a + pure thermal analysis as described above. - * ``"ON"`` : Perform a Sturm sequence check. This requires - additional matrix factorization (which can be expensive), - but does help ensure that no modes are missed in the - specified range. + numstep : str + Valid only when ``Lab`` = TEMP. A value used together with ``VALUE`` in the algorithm for + determining if the time step interval can be increased. The time step interval is increased if + the maximum absolute value of the incremental solution at the specified TEMP label is less than + ``VALUE`` for the number of contiguous time steps specified by ``NUMSTEP`` (default ``NUMSTEP`` + = 3). Notes ----- - LANBOPTION specifies options to be used with the Block Lanczos - eigensolver during an eigenvalue buckling analysis (BUCOPT,LANB) - or a modal analysis (MODOPT,LANB). - By default the sturm sequence check is off for the Block Lanczos - eigensolver when it is used in a modal analysis, and on when it is - used in a buckling analysis. + .. _OPNCONTROL_notes: - """ - return self.run(f"LANBOPTION,{strmck}", **kwargs) + This command is available only for nonlinear static or full transient analyses. :ref:`opncontrol` + enables an increase in the current time step size. It is analogous to the :ref:`cutcontrol` command, + but with the opposite effect. :ref:`cutcontrol` reduces the step size for analyses experiencing + convergence difficulties while :ref:`opncontrol` increases the step size to speed up converging + analyses. - def lumpm(self, key="", **kwargs): - """Specifies a lumped mass matrix formulation. + The increase in the current time step size via :ref:`opncontrol` occurs when: - APDL Command: LUMPM + * a trigger mechanism is encountered and - Parameters - ---------- - key - Formulation key: + * a multiplier (greater than 1.0) is set. - OFF - Use the element-dependent default mass matrix formulation (default). + Different internal heuristics are used to automatically trigger the increase of the time step for + different physics. However, for a pure thermal analysis, an additional trigger to increase the step + size can be implemented by issuing :ref:`opncontrol`,TEMP. - ON - Use a lumped mass approximation. + The multiplier is set by issuing :ref:`opncontrol`,OPENUPFACTOR, ``VALUE`` (see details for + different analysis types in the OPENUPFACTOR argument description above). - Notes - ----- - This command is also valid in PREP7. If used in SOLUTION, this command - is valid only within the first load step. + For linear full transient analysis, where the time step interval can be predominantly determined by + the estimated modal frequency (number of solution points in a cycle in the dynamic system), the + multiplier set via the OPENUPFACTOR argument may show no effect. """ - command = f"LUMPM,{key}" + command = f"OPNCONTROL,{lab},{value},{numstep}" return self.run(command, **kwargs) - def moddir(self, key="", directory="", fname="", **kwargs): - """Activates the remote read-only modal files usage. + def outaero(self, sename: str = "", timeb: str = "", dtime: str = "", **kwargs): + r"""Outputs the superelement matrices and load vectors to formatted files for aeroelastic analysis. - APDL Command: MODDIR + Mechanical APDL Command: `OUTAERO `_ Parameters ---------- - key - Key to activate the remote modal files usage - - * ``"1 (ON or YES)"`` : The program performs the analysis - using remote modal files. The files are read-only. + sename : str + Name of the superelement that models the wind turbine supporting structure. Defaults to the + current Jobname. - * ``"0 (OFF or NO)"`` : The program performs the analysis - using modal files located in the working directory - (default). - - directory - Directory path (248 characters maximum). The directory - contains the modal analysis files. The directory path - defaults to the current working directory. + timeb : str + First time at which the load vector is formed (defaults to be read from :file:`SENAME.sub` ). - fname - File name (no extension or directory path) for the modal - analysis files. The file name defaults to the current - Jobname. + dtime : str + Time step size of the load vectors (defaults to be read from :file:`SENAME.sub` ). Notes ----- - Only applies to spectrum analyses (ANTYPE,SPECTR). - Using the default for both the directory path (Directory) and the - file name (Fname) is not valid. At least one of these values must - be specified. + .. _OUTAERO_notes: + + Both TIMEB and DTIME must be blank if the time data is to be read from the :file:`SENAME.sub` file. + + The matrix file ( :file:`SENAME.SUB` ) must be available from the substructure generation run before + issuing this command. This superelement that models the wind turbine supporting structure must + contain only one master node with six freedoms per node: UX, UY, UZ, ROTX, ROTY, ROTZ. The master + node represents the connection point between the turbine and the supporting structure. - The MODDIR command must be issued during the first solution and at - the beginning of the solution phase (before LVSCALE in - particular). + This command will generate four files that are exported to the aeroelastic code for integrated wind + turbine analysis. The four files are :file:`Jobname.GNK` for the generalized stiffness matrix, + :file:`Jobname.GNC` for the generalized damping matrix, :file:`Jobname.GNM` for the generalized mass + matrix and :file:`Jobname.GNF` for the generalized load vectors. - Remote modal files usage is not supported when mode file reuse is - activated (modeReuseKey = YES on SPOPT). + For detailed information on how to perform a wind coupling analysis, see `Coupling to External + Aeroelastic Analysis of Wind Turbines + `_ """ - return self.run(f"MODDIR,{key},{directory},{fname}", **kwargs) + command = f"OUTAERO,{sename},{timeb},{dtime}" + return self.run(command, **kwargs) - def monitor(self, var="", node="", lab="", **kwargs): - """Controls contents of three variable fields in nonlinear solution + def pcgopt( + self, + lev_diff: str = "", + fallback: str = "", + reduceio: str = "", + strmck: str = "", + wrtfull: str = "", + lm_key: str = "", + **kwargs, + ): + r"""Controls PCG solver options. - APDL Command: MONITOR - monitor file. + Mechanical APDL Command: `PCGOPT `_ Parameters ---------- - var - One of three variable field numbers in the monitor file whose - contents can be specified by the Lab field. Valid arguments are - integers 1, 2, or 3. See Notes section for default values. - - node - The node number for which information is monitored in the specified - VAR field. In the GUI, if Node = P, graphical picking is enabled. - If blank, the monitor file lists the maximum value of the specified - quantity (Lab field) for the entire structure. - - lab - The solution quantity to be monitored in the specified VAR field. - Valid labels for solution quantities are UX, UY, and UZ - (displacements); ROTX, ROTY, and ROTZ (rotations); and TEMP - (temperature). Valid labels for reaction force are FX, FY, and FZ - (structural force) and MX, MY, and MZ (structural moment). Valid - label for heat flow rate is HEAT. For defaults see the Notes - section. - - Notes - ----- - The monitor file always has an extension of .mntr, and takes its file - name from the specified Jobname. If no Jobname is specified, the file - name defaults to file. + lev_diff : str + Indicates the level of difficulty of the analysis. Valid settings are AUTO or 0 (default), 1, 2, 3, + 4, or 5. This option applies to both the PCG solver when used in static and full transient analyses + and to the PCG Lanczos method in modal analyses. - You must issue this command once for each solution quantity you want to - monitor at a specified node at each load step. You cannot monitor a - reaction force during a linear analysis. The variable field contents - can be redefined at each load step by reissuing the command. The - monitored quantities are appended to the file for each load step. + * Specify AUTO to allow Mechanical APDL to select the proper level of difficulty for the model. + * Lower values (1 or 2) generally provide the best performance for well-conditioned problems. + * Values of 3 or 4 generally provide the best performance for ill-conditioned problems; however, + higher values may increase the solution time for well-conditioned problems. Higher level-of- + difficulty values typically require more memory. + * The highest value of 5 essentially performs a factorization of the global matrix (similar to the + sparse solver) and may require a very large amount of memory. This level is generally recommended + for small- to medium-sized problems when using the PCG Lanczos mode-extraction method. - Reaction forces reported in the monitor file may be incorrect if the - degree of freedom of the specified node is involved in externally - defined coupling (CP command) or constraint equations (CE command), or - if the program has applied constraint equations internally to the node. + For example, models containing elongated elements (that is, elements with high aspect ratios) and + models containing contact elements can lead to ill-conditioned problems. To determine if your + problem is ill-conditioned, view the :file:`Jobname.PCS` file to see the number of PCG iterations + needed to reach a converged solution. Generally, static or full transient solutions that require + more than 1500 iterations are considered to be ill-conditioned for the PCG solver. - The following example shows the format of a monitor file. Note that - the file only records the solution substep history when a substep is - convergent. + fallback : str + Controls whether Mechanical APDL switches to the sparse direct solver automatically ( :ref:`eqslv`,SPARSE) + under certain conditions. (The criteria are listed below.) When Mechanical APDL switched the equation + solver, the simulation attempts to continue without interruption. - The following details the contents of the various fields in the monitor - file: + * ``AUTO`` - Automatically switch to the sparse solver when one of the following conditions apply (default): - The current load step number. + * The assembled matrix is detected to be indefinite. - The current substep (time step) number. + * The PCG solver requires more than 2000 iterations to reach convergence. - The number of attempts made in solving the current substep. This - number is equal to the number of failed attempts (bisections) plus one - (the successful attempt). + * The PCG solver fails to converge. - The number of iterations used by the last successful attempt. + * ``ON`` - More aggressive fallback criteria. Automatically switch to the sparse solver when one of the + following conditions apply: - Total cumulative number of iterations (including each iteration used by - a bisection). + * The assembled matrix is detected to be indefinite. - : + * The PCG solver requires more than 1500 iterations to reach convergence. - Time or load factor increments for the current substep. + * The PCG solver fails to converge. - Total time (or load factor) for the last successful attempt in the - current substep. + * ``OFF`` - Disables the fallback logic so that there is no automatic switching, and only the PCG + solver is used to solve the equations for this simulation. - Variable field 1. In this example, the field is reporting the UZ - value. By default, this field lists the CPU time used up to (but not - including) the current substep. + After switching to the sparse solver, the program reverts back to the PCG solver under certain + conditions. See the :ref:`Notes section for details. ` - Variable field 2. In this example, the field is reporting the MZ - value. By default, this field lists the maximum displacement in the - entire structure. + reduceio : str + Controls whether the PCG solver will attempt to reduce I/O performed during equation solution: - Variable field 3. By default (and in the example), this field reports - the maximum equivalent plastic strain increment in the entire - structure. - """ - command = f"MONITOR,{var},{node},{lab}" - return self.run(command, **kwargs) + * ``AUTO`` - Automatically chooses whether to reduce I/O or not (default). - def msave(self, key="", **kwargs): - """Sets the solver memory saving option. This option only applies to the + * ``YES`` - Reduces I/O performed during equation solution in order to reduce total solver time. - APDL Command: MSAVE - PCG solver (including PCG Lanczos). + * ``NO`` - Does NOT reduce I/O performed during equation solution. - Parameters - ---------- - key - Activation key: + This option applies to both the PCG solver when used in static and full transient analyses and to + the PCG Lanczos method in modal analyses. - 0 or OFF - Use global assembly for the stiffness matrix (and mass matrix, when using PCG - Lanczos) of the entire model. + strmck : str + Controls whether or not a Sturm sequence check is performed: - 1 or ON - Use an element-by-element approach when possible to save memory during the - solution. In this case, the global stiffness (and mass) - matrix is not assembled; element stiffness (and mass) is - regenerated during PCG or PCG Lanczos iterations. + * ``OFF`` - Does NOT perform Sturm sequence check (default). + + * ``ON`` - Performs Sturm sequence check + + This option applies only when using the PCG Lanczos method in modal analyses. When using this + option, a factorization must be performed and will require a very large amount of memory for extra + computations. This option is generally recommended for small- to medium-sized problems. If the Sturm + sequence check takes a large amount of computing time, use the :file:`Jobname.ABT` file to abort the + Sturm check, or press the STOP button if in interactive mode. + + wrtfull : str + Controls whether or not the :file:`.FULL` file is written. + + * ``ON`` - Write :file:`.FULL` file (default) + + * ``OFF`` - Do not write :file:`.FULL` file. + + This option applies only when using the PCG Lanczos method in modal analyses because the + :file:`.FULL` file is never written when using the PCG solver in static or full transient analyses. + + If using :ref:`msave`,ON and conditions for the :ref:`msave` command are met, a complete + :file:`.FULL` file is never written regardless of this option. + + If constraint equations are present in the model, a :file:`.FULL` file is always written regardless + of this option. + + This option is useful in a distributed-memory parallel processing analysis because assembling the + global stiffness and mass matrices on the head compute node before writing the :file:`.FULL` file + can take a considerable amount of memory. By setting ``Wrtfull`` = OFF, this assembly process is + skipped on the head compute node, decreasing the amount of memory required to compute the modes and + mode shapes. ``Wrtfull`` = OFF does not affect the results for the modes and mode shapes. However, + without a :file:`.FULL` file, the participation factor table computations do not occur. + + To generate the :file:`.FULL` file, such as for a harmonic, transient mode-superposition, or + spectrum analysis, rerun the modal analysis with ``Wrtfull`` = ON, or use the :ref:`wrfull` command. + + lm_key : str + Controls use of the PCG solver for ``MPC184`` elements that involve the Lagrange multiplier method. + This option applies only to the PCG solver when used in static analyses, full transient analyses, + and modal analyses that use the PCG Lanczos mode-extraction method ( :ref:`modopt`,LANPCG). + + * ``ON`` - Allow use of the PCG solver with certain ``MPC184`` element types that use the Lagrange + multiplier method. (default) + + * ``OFF`` - Do not use the PCG solver with any ``MPC184`` element types that use the Lagrange + multiplier method. + + The Lagrange multiplier method used by ``MPC184`` elements transfers the Lagrange multipliers into + multiple point constraints and, hence, can be solved by the PCG solver. The current ``MPC184`` + element types supported are: `rigid beam + `_, + `rigid link + `_, + `slider + `_, + `revolute joint + `_, + `universal joint + `_, + `translational joint + `_, + `cylindrical joint + `_, + `weld joint + `_, + `spherical joint + `_, + and `general joint + `_ + . For all other ``MPC184`` element types, the PCG solver cannot be used, and the equation solver + automatically switches to the sparse solver regardless of the ``LM_Key`` setting on :ref:`pcgopt`. + The :ref:`msave` command does not support the ``LM_Key`` = ON option. Notes ----- - MSAVE,ON only applies to and is the default for parts of the model - using the following element types with linear material properties that - meet the conditions listed below. - - SOLID186 (Structural Solid only) - - SOLID187 - - The following conditions must also be true: + ``ReduceIO`` works independently of the :ref:`msave` command in the PCG solver. Setting ``ReduceIO`` + to YES can significantly increase the memory usage in the PCG solver. - The PCG solver has been specified. + To minimize the memory used by the PCG solver with respect to the ``Lev_Diff`` option only, set + ``Lev_Diff`` = 1 if you do not have sufficient memory to run the PCG solver with ``Lev_Diff`` = + AUTO. - Small strains are assumed (NLGEOM,OFF). + The :ref:`msave`,ON command is not valid in these circumstances: - No prestress effects (PSTRES) are included. + * when ``Lev_Diff`` = 5; in this case, the ``Lev_Diff`` value will automatically be reset to 2. - All nodes on the supported element types must be defined (i.e., the - midside nodes cannot be removed using the EMID command). + * with the ``StrmCk`` option; in this case, ``StrmCk`` will be set to OFF. - For elements with thermally dependent material properties, MSAVE,ON - applies only to elements with uniform temperatures prescribed. + * when the ``Fallback`` option is enabled (set to AUTO or ON); in this case, ``Fallback`` will + automatically be reset to OFF. - The default element coordinate system must be used. + For Lagrange-formulation contact methods and mixed u-P formulations, the PCG solver cannot be used, + and the sparse solver is required. - If you manually force MSAVE,ON by including it in the input file, the - model can include the following additional conditions: + ``Fallback`` logic is automatically disabled ( ``Fallback`` = OFF) in these circumstances: - The analysis can be a modal analysis using the PCG Lanczos method - (MODOPT,LANPCG). + * for analyses that include ``MPC184`` elements using the Lagrange multiplier method to impose + kinematic constraints - Large deflection effects (NLGEOM,ON) are included. + * for thermal analyses that use the quasi-static ( :ref:`thopt`,QUASI) option. - SOLID185 (brick shapes and KEYOPT(2) = 3 only) elements can be - included. + **Reverting to the PCG Solver After an Automatic Switch to the Sparse Solver** - All other element types or other parts of the model that don't meet the - above criteria will be solved using global assembly (MSAVE,OFF). This - command can result in memory savings of up to 70 percent over the - global assembly approach for the part of the model that meets the - criteria. Depending on the hardware (e.g., processor speed, memory - bandwidth, etc.), the solution time may increase or decrease when this - feature is used. + **Linear Analysis:** When fallback logic is enabled ( ``Fallback`` = AUTO or ON) and the program + switches to the sparse direct solver during a linear analysis, the sparse solver is used for the + remainder of the simulation unless the solver choice is changed by issuing the :ref:`eqslv` command + between load steps. - This memory-saving feature runs in parallel when multiple processors - are used with the /CONFIG command or with Distributed ANSYS. The gain - in performance with using multiple processors with this feature turned - on should be similar to the default case when this feature is turned - off. Performance also improves when using the uniform reduced - integration option for SOLID186 elements. + **Nonlinear Analysis:** If the program switches to the sparse direct solver during a nonlinear + analysis, the sparse solver + is used for the remaining equilibrium iterations of the current substep. The program reverts back to + the PCG solver at the end of the current substep unless one of the following conditions apply: - This command does not support the layered option of the SOLID185 and - SOLID186 elements. + * The previous call to the sparse solver involved an indefinite or near-singular matrix. - When using MSAVE,ON with the PCGOPT command, note the following - restrictions: + * The last equilibrium iteration of the current substep using the sparse solver was faster than the + last successful equilibrium iteration using the PCG solver. - For static and modal analyses, MSAVE,ON is not valid when using a - Lev_Diff value of 5 on the PCGOPT command; Lev_Diff will automatically - be reset to 2. + * Three consecutive fallback switches between the sparse and the PCG solvers have occurred. - For modal analyses, MSAVE,ON is not valid with the StrmCk option of the - PCGOPT command; Strmck will be set to OFF. + For both linear and nonlinear analyses, the solver choice can be changed using the :ref:`eqslv` + command between any subsequent load steps. + """ + command = f"PCGOPT,{lev_diff},{fallback},{reduceio},{strmck},{wrtfull},{lm_key}" + return self.run(command, **kwargs) - For all analysis types, MSAVE,ON is not valid when the Lagrange - multiplier option (LM_Key) of the PCGOPT command is set to ON; the - MSAVE activation key will be set to OFF. + def perturb( + self, + type_: str = "", + matkey: str = "", + contkey: str = "", + loadcontrol: str = "", + **kwargs, + ): + r"""Sets linear perturbation analysis options. - For linear perturbation static and modal analyses, MSAVE,ON is not - valid; the MSAVE activation key will be set to OFF. + Mechanical APDL Command: `PERTURB `_ - When using MSAVE,ON for modal analyses, no .FULL file will be created. - The .FULL file may be necessary for subsequent analyses (e.g., - harmonic, transient mode-superposition, or spectrum analyses). To - generate the .FULL file, rerun the modal analysis using the WRFULL - command. - """ - command = f"MSAVE,{key}" - return self.run(command, **kwargs) + **Command default:** - def msolve(self, numslv="", nrmtol="", nrmchkinc="", **kwargs): - """Starts multiple solutions for random acoustics analysis with diffuse + .. _PERTURB_default: - APDL Command: MSOLVE - sound field. + Linear perturbation analysis is disabled ( ``Type`` = OFF) by default. When the linear perturbation + analysis is enabled, linear material property behavior is assumed for stress calculations; contact + status for all contact pairs from the point of restart is used by default; and all loads and + constraints from the restart step are deleted, except for displacement constraints and inertia + loads, by default. Parameters ---------- - numslv - Number of multiple solutions (load steps) corresponding to the - number of samplings. Default = 1. + type_ : str + Type of linear perturbation analysis to be performed: - Notes - ----- - The MSOLVE command starts multiple solutions (load steps) for random - acoustics analysis with multiple samplings. + * ``STATIC`` - Perform a linear perturbation static analysis. - The process is controlled by the norm convergence tolerance NRMTOL or - the number of multiple solutions NUMSLV (if the solution steps reach - the defined number). + * ``MODAL`` - Perform a linear perturbation modal analysis. - The program checks the norm convergence by comparing two averaged sets - of radiated sound powers with the interval NRMCHKINC over the frequency - range. For example, if NRMCHKINC = 5, the averaged values from 5 - solutions are compared with the averaged values from 10 solutions, then - the averaged values from 10 solutions are compared with the averaged - values from 15 solutions, and so on. + * ``BUCKLE`` - Perform a linear perturbation eigenvalue buckling analysis. - The incident diffuse sound field is defined via the DFSWAVE command. + * ``HARMONIC`` - Perform a linear perturbation full harmonic analysis. - The average result of multiple solutions with different samplings is - calculated via the PLST command. - """ - command = f"MSOLVE,{numslv},{nrmtol},{nrmchkinc}" - return self.run(command, **kwargs) + * ``SUBSTR`` - Perform a linear perturbation substructure generation pass. - def opncontrol(self, lab="", value="", numstep="", **kwargs): - """Sets decision parameter for automatically increasing the time step + * ``OFF`` - Do not perform a linear perturbation analysis (default). - APDL Command: OPNCONTROL - interval. + matkey : str + Key for specifying how the linear perturbation analysis uses material properties, valid for all + structural elements except contact elements. For more information, see `Linear Perturbation Analysis `_ - Parameters - ---------- - lab - DOF + * ``AUTO`` - The program selects the material properties for the linear perturbation analysis automatically + (default). The materials are handled in the following way: - DOF - Degree-of-freedom label used to base a decision for increasing the time step - (substep) interval in a nonlinear or transient analysis. - The only DOF label currently supported is TEMP. + * For pure linear elastic materials used in the base analysis, the same properties are used in the + linear perturbation analysis. - OPENUPFACTOR - Factor for increasing the time step interval. Specify when AUTOTS,ON is issued - and specify a VALUE > 1.0 (up to 10.0). The default - VALUE = 1.5 (except for thermal analysis, where it - is 3.0). Generally, VALUE > 3.0 is not recommended. + * For hyperelastic materials used in the base analysis, the material properties are assumed to be + linear elastic in the linear perturbation analysis. The material property data (or material + Jacobian) is obtained based on the tangent of the hyperelastic material's constitutive law at the + point where restart occurs. - value, numstep - Two values used in the algorithm for determining if the time step - interval can be increased. Valid only when Lab = DOF. + * For hyperviscoelastic materials used in the base analysis, the program uses the harmonic material + formulation in perturbed full harmonic solutions. - Notes - ----- - This command is available only for nonlinear or full transient - analysis. - """ - command = f"OPNCONTROL,{lab},{value},{numstep}" - return self.run(command, **kwargs) + * For other nonlinear materials used in the base analysis, the material properties are assumed to be + linear elastic in the linear perturbation analysis. The material data is the same as the linear + portion of the nonlinear materials (that is, the parts defined via :ref:`mp` commands). - def outaero(self, sename="", timeb="", dtime="", **kwargs): - """Outputs the superelement matrices and load vectors to formatted files + * For ``COMBIN39``, the stiffness is that of the first segment of the force-deflection curve. - APDL Command: OUTAERO - for aeroelastic analysis. + * ``TANGENT`` - Use the tangent (material Jacobian) on the material constitutive curve as the material property. The + material property remains linear in the linear perturbation analysis and is obtained at the point of + the base analysis where restart occurs. The materials are handled in the following way: - Parameters - ---------- - sename - Name of the superelement that models the wind turbine supporting - structure. Defaults to the current Jobname. + * For pure linear elastic materials used in the base analysis, the same properties are used in the + linear perturbation analysis. Because the material constitutive curve is linear, the tangent is + the same as the base analysis. - timeb - First time at which the load vector is formed (defaults to be read - from SENAME.sub). + * For hyperelastic materials used in the base analysis, the program uses the same tangent as that + used for ``MatKey`` = AUTO, and the results are therefore identical. - dtime - Time step size of the load vectors (defaults to be read from - SENAME.sub). + * For hyperviscoelastic materials used in the base analysis, the program uses the harmonic material + formulation in perturbed full harmonic solutions. - Notes - ----- - Both TIMEB and DTIME must be blank if the time data is to be read from - the SENAME.sub file. - - The matrix file (SENAME.SUB) must be available from the substructure - generation run before issuing this command. This superelement that - models the wind turbine supporting structure must contain only one - master node with six freedoms per node: UX, UY, UZ, ROTX, ROTY, ROTZ. - The master node represents the connection point between the turbine and - the supporting structure. - - This command will generate four files that are exported to the - aeroelastic code for integrated wind turbine analysis. The four files - are Jobname.GNK for the generalized stiffness matrix, Jobname.GNC for - the generalized damping matrix, Jobname.GNM for the generalized mass - matrix and Jobname.GNF for the generalized load vectors. - - For detailed information on how to perform a wind coupling analysis, - see Coupling to External Aeroelastic Analysis of Wind Turbines in the - Mechanical APDL Advanced Analysis Guide. - """ - command = f"OUTAERO,{sename},{timeb},{dtime}" - return self.run(command, **kwargs) + * For other nonlinear materials used in the base analysis, the material properties are assumed to be + linear elastic in the linear perturbation analysis. The material data is the same as the linear + portion of the nonlinear materials (that is, the parts defined via :ref:`mp` commands). - def ovcheck(self, method="", frequency="", set_="", **kwargs): - """Checks for overconstraint among constraint equations and Lagrange + The materials and properties typically differ from ``Matkey`` = AUTO, but it is possible the results + could be identical or very similar if a.) the material is elastoplastic rate-independent and is + unloading (or has neutral loading) at the restart point, or b.) the material is rate-dependent, + depending on the material properties and loading conditions. - APDL Command: OVCHECK - multipliers. + * For ``COMBIN39``, the stiffness is equal to the tangent of the current segment of the force- + deflection curve. - Parameters - ---------- - method - Method used to determine which slave DOFs will be eliminated: + * In a modal restart solution that follows a linear perturbation modal analysis, the TANGENT option + is overridden by the AUTO option and linear material properties are used for stress calculations + in the modal restart. See the :ref:`discussion in the Notes for more information. ` + + * ``SPOFF`` - Provide the same values as AUTO, but set the spin softening matrix to zero (ignoring + the spin softening effect). - TOPO - Topological approach (default). This method only works with constraint - equations; it does not work with Lagrange multipliers. + The spin softening effect is excluded in all the linear perturbation analysis types except for + linear perturbation buckling. Note that although the spin softening effect is excluded in linear + perturbation analysis, it is still included in the base static or full transient analysis if + :ref:`nlgeom`,ON is issued in the base analysis. - ALGE - Algebraic approach. + contkey : str + Key that controls contact status for the linear perturbation analysis. This key controls all contact + elements ( ``TARGE169``, ``TARGE170``, ``CONTA172``, ``CONTA174``, ``CONTA175``, ``CONTA177``, and + ``CONTA178`` ) globally for all contact pairs. Alternatively, contact status can be controlled + locally per contact pair by using the :ref:`cnkmod` command. Note that the contact status from the base analysis solution is always adjusted by the local contact controls specified by :ref:`cnkmod` first and then modified by the global sticking or bonded control ( ``ContKey`` = STICKING or BONDED). The tables in the `Notes `_ Notes section show how the contact status is adjusted by :ref:`cnkmod` and/or the ``ContKey`` setting. - NONE - Do not use overconstraint detection logic. + * ``CURRENT`` - Use the current contact status from the restart snapshot (default). If the previous + run is nonlinear, then the nonlinear contact status at the point of restart is frozen and used + throughout the linear perturbation analysis. - frequency - Frequency of overconstraint detection for static or full transient - analyses: + * ``STICKING`` - For frictional contact pairs (MU > 0), use sticking contact (for example, MU\*KN for + tangential contact stiffness) everywhere the contact state is closed (that is, status is sticking or + sliding). This option only applies to contact pairs that are in contact and have a frictional + coefficient MU greater than zero. Contact pairs without friction (MU = 0) and in a sliding state + remain free to slide in the linear perturbation analysis. - ITERATION - For all equilibrium iterations (default). + * ``BONDED`` - Any contact pairs that are in the closed (sticking or sliding) state are moved to + bonded (for example, KN for both normal and tangential contact stiffness). Contact pairs that have a + status of far-field or near-field remain open. - SUBSTEP - At the beginning of each substep. + loadcontrol : str + Key that controls how the load vector of {F:sub:`perturbed` } is calculated. This control is provided for convenience of load generation for linear perturbation analysis. In general, a new set of loads is required for a linear perturbation analysis. This key controls all mechanical loads; it does not affect non-mechanical loads. Non-mechanical loads (including thermal loads) are always kept (that is, not deleted). - LOADSTEP - At the beginning of each load step. + * ``ALLKEEP`` - Keep all the boundary conditions (loads and constraints) from the end of the load + step of the current restart point. This option is convenient for further load application and is + useful for a linear perturbation analysis restarted from a previous linear analysis. For this + option, {F:sub:`end` } is the total load vector at the end of the load step at the restart point. - set\\_ - Set of equations: + * ``INERKEEP`` - Delete all loads and constraints from the restart step, except for displacement + constraints and inertia loads (default). All displacement constraints and inertia loads are kept for + convenience when performing the linear perturbation analysis. Note that nonzero and tabular + displacement constraints can be considered as external loads; however, they are not deleted when + using this option. - All - Check for overconstraint between all constraint equations (default). + * ``PARKEEP`` - Delete all loads and constraints from the restart step, except for displacement + constraints. All displacement constraints are kept for convenience when performing the linear + perturbation analysis. Note that nonzero and tabular displacement constraints can be considered as + external loads; however, they are not deleted when using this option. - LAG - Check for overconstraint only on the set of equations that involves Lagrange - multipliers. This is faster than checking all sets, - especially when the model contains large MPC bonded contact - pairs. + * ``DZEROKEEP`` - Behaves the same as the PARKEEP option, except that all nonzero displacement + constraints are set to zero upon the onset of linear perturbation. + + * ``NOKEEP`` - Delete all the loads and constraints, including all displacement constraints. For + this option, {F:sub:`end` } is zero unless non-mechanical loads (for example, thermal loads) are + present. Notes ----- - The OVCHECK command checks for overconstraint among the constraint - equations (CE/CP) and the Lagrange multipliers for the globally - assembled stiffness matrix. If overconstrained constraint equations or - Lagrange multipliers are detected, they are automatically removed from - the system of equations. - - The constraint equations that are identified as redundant are removed - from the system and printed to the output file. It is very important - that you check the removed equations—they may lead to convergence - issues, especially for nonlinear analyses. - - The Frequency and Set arguments are active only for the topological - method (Method = TOPO). If you do not issue the OVCHECK command, - overconstraint detection is performed topologically, and the slave DOFs - are also determined topologically. - - Overconstraint detection slows down the run. We recommend using it to - validate that your model does not contain any overconstraints. Then, - you can switch back to the default method (no OVCHECK command is - needed). - - As an example, consider the redundant set of constraint equations - defined below: - - Equation number 2 will be removed by the overconstraint detection - logic. However, this is an arbitrary decision since equation number 1 - could be removed instead. This is an important choice as the constant - term is not the same in these two constraint equations. Therefore, you - must check the removed constraint equations carefully. - - For detailed information on the topological and algebraic methods of - overconstraint detection, see Constraints: Automatic Selection of Slave - DOFs in the Mechanical APDL Theory Reference - """ - command = f"OVCHECK,{method},{frequency},{set_}" - return self.run(command, **kwargs) - def pcgopt( - self, - lev_diff="", - reduceio="", - strmck="", - wrtfull="", - memory="", - lm_key="", - **kwargs, - ): - """Controls PCG solver options. + .. _PERTURB_notes: - APDL Command: PCGOPT + This command controls options relating to `linear perturbation analyses + `_. It must be + issued in the first phase of a linear perturbation analysis. - Parameters - ---------- - lev_diff - Indicates the level of difficulty of the analysis. Valid - settings are AUTO or 0 (default), 1, 2, 3, 4, or 5. This - option applies to both the PCG solver when used in static - and full transient analyses and to the PCG Lanczos method - in modal analyses. Use AUTO to let ANSYS automatically - choose the proper level of difficulty for the model. Lower - values (1 or 2) generally provide the best performance for - well-conditioned problems. Values of 3 or 4 generally - provide the best performance for ill-conditioned problems; - however, higher values may increase the solution time for - well-conditioned problems. Higher level-of-difficulty - values typically require more memory. Using the highest - value of 5 essentially performs a factorization of the - global matrix (similar to the sparse solver) and may - require a very large amount of memory. If necessary, use - Memory to reduce the memory usage when using Lev_Diff = 5. - Lev_Diff = 5 is generally recommended for small- to - medium-sized problems when using the PCG Lanczos mode - extraction method. - - reduceio - Controls whether the PCG solver will attempt to reduce I/O - performed during equation solution: - - AUTO - Automatically chooses whether to reduce I/O or not - (default). - - YES - Reduces I/O performed during equation solution in - order to reduce total solver time. - - NO - Does NOT reduce I/O performed during equation solution. - - strmck - Controls whether or not a Sturm sequence check is performed: + This command is also valid in PREP7. + + A linear perturbation analysis consists of two phases (two :ref:`solve` commands). The first phase + is a restart from a base analysis. This base analysis must be a linear or nonlinear static analysis + or full transient analysis. The first phase starts with the :ref:`antype`,,RESTART,,,PERTURB + command and ends with the :ref:`solve`,ELFORM command. The purpose of the first phase is to re- + establish a snapshot of the stiffness matrices at the specified restart point. The second phase, + ending with the second :ref:`solve` command, is for the actual linear perturbation analysis. + + The total perturbed loads are calculated as follows: + + {F:sub:`perturbed` } = {F:sub:`end` } + {F:sub:`add` } + + where: + + * {F :sub:`end` } = total loads at the end of the load step of the current restart point (load + applications are read from the :file:`.LDHI` file). By default, all of the loads in {F :sub:`end` + } are deleted except for displacement boundary conditions and inertia loads (see the description + of ``LoadControl`` above). + * {F :sub:`add` } = Additional (new) loads prescribed by the user in the second phase of the linear + perturbation analysis (after the first :ref:`solve` command is invoked). + + In the first phase of a linear perturbation analysis, the :ref:`antype`,,RESTART command resumes the + :file:`Jobname.RDB` database and reads in the :file:`.LDHI` file to establish the {F:sub:`end` } + load. New load application (adding to {F:sub:`add` }) or load removal (changing {F:sub:`end` }) can + be done only in the second phase of the linear perturbation analysis (after the first :ref:`solve` + command), allowing flexibility in controlling the final {F:sub:`perturbed` } to be used. + + For ``Type`` = STATIC, {F:sub:`perturbed` } is the actual external load for the static analysis. + + For ``Type`` = MODAL, {F:sub:`perturbed` } is calculated and stored in the :file:`.FULL` and + :file:`.MODE` files for a subsequent mode-superposition, PSD, or other type of modal-based linear + dynamic analysis. Linear dynamic options such as multiple load generations ( :ref:`modcont`,ON), + enforced motion ( :ref:`modcont`,,ON), and residual vector methods ( :ref:`resvec`,ON) can be used + in a linear perturbation analysis. For these methods, the :ref:`modcont` or :ref:`resvec` command + must be invoked in the second phase (after the first :ref:`solve` ) of the linear perturbation + procedure. For the enforced motion method, the base identification number should be specified ( + :ref:`d` command) in the second phase of the linear perturbation analysis. This base identification + number is used later in the downstream mode-superposition or other mode-superposition based + analysis. + + For ``Type`` = BUCKLE, {F:sub:`perturbed` } is the actual linear buckling load which is used to + generate the linear stress stiffening matrix for the buckling analysis. + + For ``Type`` = HARMONIC, {F:sub:`perturbed` } is the actual external load for the full harmonic + analysis. In this case, {F:sub:`perturbed` } can be frequency dependent and can use complex input. + + For ``Type`` = SUBSTR, {F:sub:`perturbed` } is used to generate the first reduced external load + vector of the substructure. + + In most cases involving linear perturbation analysis, ``Matkey`` = AUTO is the best option for + controlling material behavior. ``Matkey`` = TANGENT is often the better option, however, in special + cases such as the following: + + * A linear perturbation buckling analysis, to introduce preferred buckling modes into a subsequent + post-buckling nonlinear analysis. + + * A linear perturbation modal analysis, to introduce preferred modes into a subsequent bifurcation + analysis. + + If the TANGENT option is used in conjunction with a modal restart solution that follows a linear + perturbation modal analysis, then the AUTO option is assumed and linear material properties are used + for stress calculations in the modal restart solution. This occurs because the TANGENT material + properties are not available during the modal restart phase due to a data architecture limitation. + Furthermore, linear material properties are used for the stress calculation in any downstream + analysis that uses the modal restart solution. + + For more information about the automatic and tangent options, see in the `Element Reference + `_. + + You can control the contact status for the linear perturbation analysis by using the ``ContKey`` + field on this command and/or the :ref:`cnkmod` command. The first table shows the effects of using + only the ``ContKey`` setting on the :ref:`perturb` command. The second table shows the effects of + using both the :ref:`cnkmod` command and the ``ContKey`` setting on :ref:`perturb`. + + Adjusted Contact Status when PERTURB Command Is Issued + ****************************************************** + + .. flat-table:: + + * - :rspan:`1` **Contact Status from the Base Analysis Solution at the Restart Point** + - **ContKeySetting on PERTURB Command** + * - ``ContKey`` Value + - Adjusted Contact Status + * - 0 - far-field + - any + - 0 - far-field + * - 1 - near-field + - any + - 1 - near-field + * - :rspan:`1` 2 - sliding + - CURRENT or STICKING (mu=0) + - 2 - sliding + * - STICKING (mu>0) or BONDED + - 3 - sticking + * - 3 - sticking + - any + - 3 - sticking + + Adjusted Contact Status when Both CNKMOD and PERTURB Are Issued + *************************************************************** + + .. flat-table:: + + * - :rspan:`1` **Contact Status from the Base Analysis Solution at the Restart Point** + - *\*CNKMOD,** ``ITYPE`` ,12, ``Value`` + - **ContKeySetting on PERTURB Command** + * - KEYOPT(12) Value + - Adjusted Contact Status + - ``ContKey`` Value + - Final Adjusted Contact Status + * - 0 - far-field + - any + - 0 - far-field + - any + - 0 - far-field + * - :rspan:`5` 1 - near-field + - 0, 1, 2, 3, 6 + - 1 - near-field + - any + - 1 - near-field + * - :rspan:`2` 4 + - 1 - near-field (if outside of the adjusted pinball region) + - any + - 1 - near-field + * - :rspan:`1` 2 - sliding (if inside of the adjusted pinball region) + - CURRENT or STICKING (mu=0) + - 2 - sliding + * - STICKING (mu>0) or BONDED + - 3 - sticking + * - :rspan:`1` 5 + - 1 - near-field (if outside of the adjusted pinball region) + - any + - 1 - near-field + * - 3 - sticking (if inside of the adjusted pinball region) + - any + - 3 - sticking + * - :rspan:`2` 2 - sliding + - :rspan:`1` 0, 2, 4 + - :rspan:`1` 2 - sliding + - CURRENT or STICKING (mu=0) + - 2 - sliding + * - STICKING (mu>0) or BONDED + - 3 - sticking + * - 1, 3, 5, 6 + - 3 - sticking + - any + - 3 - sticking + * - 3 - sticking + - any + - 3 - sticking + - any + - 3 - sticking + + When ``ContKey`` is set to CURRENT, all contact related parameters (such as normal stiffness and + tangential stiffness) will remain unchanged throughout the linear perturbation analysis. However + when ``ContKey`` is set to STICKING or BONDED, the program will re-evaluate the contact normal and + tangential stiffness in order to perform the linear perturbation analysis based on the actual + sticking behavior regardless of the friction coefficient value. + + Note that the :ref:`cnkmod` command allows you to take points in the base analysis that are near + contact (within the pinball region) and modify them to be treated as "in contact" in the linear + perturbation analysis; see the "1 - near-field" row in the above table with KEYOPT(12) values set to + 4 or 5. :ref:`cnkmod` also allows you to take points that are sliding in the base analysis and treat + them as sticking in the linear perturbation analysis, irrespective of the MU value; see the "2 - + sliding" row in the above table with KEYOPT(12) values set to 1,5, or 6. + + If an open gap exists at the restart point of the base static/transient solution and the contact + status is adjusted as sliding or sticking due to a “bonded” or “no separation” contact behavior + definition, then the program will treat it as near-field contact when executing the :ref:`cnkmod` + command in a downstream linear perturbation analysis. + """ + command = f"PERTURB,{type_},{matkey},{contkey},{loadcontrol}" + return self.run(command, **kwargs) + + def pivcheck(self, key: str = "", prntcntrl: str = "", **kwargs): + r"""Controls the behavior of an analysis when a negative or zero equation solver pivot value is + encountered. - OFF - Does NOT perform Sturm sequence check (default). + Mechanical APDL Command: `PIVCHECK `_ - ON - Performs Sturm sequence check + **Command default:** - wrtfull - Controls whether or not the .FULL file is written. + .. _PIVCHECK_default: - ON - Write .FULL file (default) + The program checks for negative or zero pivot values ( ``Key`` = AUTO). If any are found, the + analysis may stop with an error or may proceed with only a warning, depending on various criteria + pertaining to the type of analysis being solved. - OFF - Do not write .FULL file. + Parameters + ---------- + key : str + Determines whether to stop or continue an analysis when a negative or zero equation solver pivot + value is encountered: - memory - Controls whether to run using in-core or out-of-core mode - when using Lev_Diff = 5. + * ``AUTO`` - Check for negative or zero pivot values for analyses performed with the sparse and PCG + solvers. When one is encountered, an error or warning is issued, per various criteria relating to + the type of analysis being solved. An error causes the analysis to stop; a warning allows the + analysis to continue. A negative pivot value may be valid for some nonlinear and multiphysics + analyses (for example, electromagnetic and thermal analyses); this key has no effect in these cases. - AUTO - Automatically chooses which mode to use (default). + * ``ERROR`` - Check for negative or zero pivot values for analyses performed with the sparse and PCG + solvers. When one is encountered, an error is issued, stopping the analysis. A negative pivot value + may be valid for some nonlinear and multiphysics analyses (for example, electromagnetic and thermal + analyses); this key has no effect in these cases. - INCORE - Run using in-core mode. + * ``WARN`` - Check for negative or zero pivot values for analyses performed with the sparse and PCG + solvers. When one is encountered, a warning is issued and the analysis continues. A negative pivot + value may be valid for some nonlinear and multiphysics analyses (for example, electromagnetic and + thermal analyses); this key has no effect in these cases. - OOC - Run using out-of-core mode. + * ``OFF`` - Pivot values are not checked. This key causes the analysis to continue in spite of a + negative or zero pivot value. - lm_key - Controls use of the PCG solver for MPC184 Lagrange - multiplier method elements. This option applies only to - the PCG solver when used in static and full transient - analyses. + prntcntrl : str + Provides print options. Print output with these options will be sent to the default output file, not + to the files created by the nonlinear diagnostic tools ( :ref:`nldiag` ). - OFF - Do not use the PCG solver for the MPC184 Lagrange - multiplier method (default). + * ``ONCE`` - Print only the maximum and minimum pivot information on the first call to the sparse + solver (which is the default solver). This is the default behavior. - ON - Allow use of the PCG solver for the MPC184 Lagrange - multiplier method. + * ``EVERY`` - Print the maximum and minimum pivot information at every call to the sparse solver. + This option is provided for nonlinear analysis diagnostics. Notes ----- - ReduceIO works independently of the MSAVE command in the PCG - solver. Setting ReduceIO to YES can significantly increase - the memory usage in the PCG solver. - To minimize the memory used by the PCG solver with respect to - the Lev_Diff option only, set Lev_Diff = 1 if you do not have - sufficient memory to run the PCG solver with Lev_Diff = AUTO. + .. _PIVCHECK_notes: - The MSAVE,ON command is not valid when using Lev_Diff = 5. In - this case, the Lev_Diff value will automatically be reset to - 2. The MSAVE,ON command is also not valid with the StrmCk - option. In this case, StrmCk will be set to OFF. + This command is valid for all analyses. In a nonlinear analysis, a negative pivot may be valid. In + some cases, rigid body motions in a nonlinear analysis will be trapped by error routines checking + infinitely large displacements (DOF limit exceeded) or nonconvergence status. An under-constrained + model may avoid the pivot check, but fail with a DOF limit exceeded error. - Distributed ANSYS Restriction: The Memory option and the - LM_Key option are not supported in Distributed ANSYS. + Machine precision may affect whether a small pivot triggers an error or bypasses this checking + logic. You may wish to review the ratio of the maximum to absolute minimum pivot values. For ratios + exceeding 12 to 14 orders of magnitude, the accuracy of the computed solution may be degraded by the + severe ill-conditioning of the assembled matrix. + + Note that negative pivots corresponding to Lagrange multiplier based mixed u-P elements are not + checked or reported by this command. Negative pivots arising from the u-P element formulation and + related analyses can occur and lead to correct solutions. + + This command is also valid in PREP7. """ - command = f"PCGOPT,{lev_diff},,{reduceio},{strmck},{wrtfull},{memory},{lm_key}" + command = f"PIVCHECK,{key},{prntcntrl}" return self.run(command, **kwargs) - def perturb(self, type_="", matkey="", contkey="", loadcontrol="", **kwargs): - """Sets linear perturbation analysis options. + def prscontrol(self, key: str = "", **kwargs): + r"""Specifies whether to include pressure load stiffness in the element stiffness formation. - APDL Command: PERTURB + Mechanical APDL Command: `PRSCONTROL `_ Parameters ---------- - type\\_ - Type of linear perturbation analysis to be performed: + key : str + Pressure load stiffness key. In general, use the default setting. Use a non-default setting only if + you encounter convergence difficulties. Pressure load stiffness is automatically included when using + eigenvalue buckling analyses ( :ref:`antype`,BUCKLE), equivalent to ``Key`` = INCP. For all other types of analyses, valid arguments for ``Key`` are: - STATIC - Perform a linear perturbation static analysis. - - MODAL - Perform a linear perturbation modal analysis. - - BUCKLE - Perform a linear perturbation eigenvalue buckling analysis. - - HARMONIC - Perform a linear perturbation full harmonic analysis. - - SUBSTR - Perform a linear perturbation substructure generation pass. - - OFF - Do not perform a linear perturbation analysis (default). - - matkey - Key for specifying how the linear perturbation analysis uses - material properties, valid for all structural elements except - contact elements. For more information, see Linear Perturbation - Analysis in the Mechanical APDL Theory Reference. - - AUTO - The program selects the material properties for the linear perturbation - analysis automatically (default). The materials are handled - in the following way: - - For pure linear elastic materials used in the base analysis, the same properties are used in the linear perturbation analysis. - For hyperelastic materials used in the base analysis, the material properties - are assumed to be linear elastic in the linear - perturbation analysis. The material property data - (or material Jacobian) is obtained based on the - tangent of the hyperelastic material's - constitutive law at the point where restart - occurs. - - For any nonlinear materials other than hyperelastic materials used in the base analysis, the material properties are assumed to be linear elastic in the linear perturbation analysis. The material data is the same as the linear portion of the nonlinear materials (that is, the parts defined by MP commands). - For COMBIN39, the stiffness is that of the first segment of the force- - deflection curve. - - TANGENT - Use the tangent (material Jacobian) on the material constitutive curve as the - material property. The material property remains linear - in the linear perturbation analysis and is obtained at - the point of the base analysis where restart occurs. The - materials are handled in the following way: - - For pure linear elastic materials used in the base analysis, the same properties are used in the linear perturbation analysis. Because the material constitutive curve is linear, the tangent is the same as the base analysis. - For hyperelastic materials used in the base analysis, the program uses the same - tangent as that used for MatKey = AUTO, and the - results are therefore identical. - - For any nonlinear materials other than hyperelastic materials used in the base analysis, the material properties are obtained via the material tangent on the material constitutive curve at the restart point of the base analysis. - The materials and properties typically differ from Matkey = AUTO, but it is - possible the results could be identical or very - similar if a.) the material is elasto-plastic - rate-independent and is unloading (or has neutral - loading) at the restart point, or b.) the - material is rate-dependent, depending on the - material properties and loading conditions. - - For COMBIN39, the stiffness is equal to the tangent of the current segment of the force-deflection curve. - In a modal restart solution that follows a linear perturbation modal analysis, - the TANGENT option is overridden by the AUTO - option and linear material properties are used - for stress calculations in the modal restart. See - the discussion in the Notes for more information. - - contkey - Key that controls contact status for the linear perturbation - analysis. This key controls all contact elements (TARGE169, - TARGE170, and CONTA171 through CONTA178) globally for all contact - pairs. Alternatively, contact status can be controlled locally per - contact pair by using the CNKMOD command. Note that the contact - status from the base analysis solution is always adjusted by the - local contact controls specified by CNKMOD first and then modified - by the global sticking or bonded control (ContKey = STICKING or - BONDED). The tables in the Notes section show how the contact - status is adjusted by CNKMOD and/or the ContKey setting. - - CURRENT - Use the current contact status from the restart - snapshot (default). If the previous run is - nonlinear, then the nonlinear contact status at - the point of restart is frozen and used - throughout the linear perturbation analysis. - - STICKING - For frictional contact pairs (MU > 0), use - sticking contact (e.g., ``MU*KN`` for tangential - contact stiffness) everywhere the contact state - is closed (i.e., status is sticking or - sliding). This option only applies to contact - pairs that are in contact and have a frictional - coefficient MU greater than zero. Contact pairs - without friction (MU = 0) and in a sliding - state remain free to slide in the linear - perturbation analysis. - - BONDED - Any contact pairs that are in the closed - (sticking or sliding) state are moved to bonded - (for example, KN for both normal and tangential - contact stiffness). Contact pairs that have a - status of far-field or near-field remain open. - - loadcontrol - Key that controls how the load vector of {Fperturbed} is - calculated. This control is provided for convenience of load - generation for linear perturbation analysis. In general, a new set - of loads is required for a linear perturbation analysis. This key - controls all mechanical loads; it does not affect non-mechanical - loads. Non-mechanical loads (including thermal loads) are always - kept (i.e., not deleted). - - ALLKEEP - Keep all the boundary conditions (loads and - constraints) from the end of the load step of - the current restart point. This option is - convenient for further load application and is - useful for a linear perturbation analysis - restarted from a previous linear analysis. For - this option, {Fend} is the total load vector at - the end of the load step at the restart point. - - INERKEEP - Delete all loads and constraints from the - restart step, except for displacement - constraints and inertia loads (default). All - displacement constraints and inertia loads are - kept for convenience when performing the linear - perturbation analysis. Note that nonzero and - tabular displacement constraints can be - considered as external loads; however, they are - not deleted when using this option. - - PARKEEP - Delete all loads and constraints from the - restart step, except for displacement - constraints. All displacement constraints are - kept for convenience when performing the linear - perturbation analysis. Note that nonzero and - tabular displacement constraints can be - considered as external loads; however, they are - not deleted when using this option. - - DZEROKEEP - Behaves the same as the PARKEEP option, except - that all nonzero displacement constraints are - set to zero upon the onset of linear - perturbation. - - NOKEEP - Delete all the loads and constraints, including - all displacement constraints. For this option, - {Fend} is zero unless non-mechanical loads (e.g., - thermal loads) are present. + * ``NOPL`` - Pressure load stiffness not included for any elements. + + * ``(blank) (default)`` - Include pressure load stiffness for elements ``SURF153``, ``SURF154``, + ``SURF156``, ``SURF159``, ``SHELL181``, ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, + ``SOLID187``, ``SOLSH190``, ``BEAM188``, ``BEAM189``, ``FOLLW201``, ``SHELL208``, ``SHELL209``, + ``SOLID272``, ``SOLID273``, ``SHELL281``, ``SOLID285``, ``PIPE288``, ``PIPE289``, and ``ELBOW290``. Notes ----- - This command controls options relating to linear perturbation analyses. - It must be issued in the first phase of a linear perturbation analysis. - This command is also valid in PREP7. + .. _PRSCONTROL_notes: + + This command is rarely needed. The default settings are recommended for most analyses. """ - command = f"PERTURB,{type_},{matkey},{contkey},{loadcontrol}" + command = f"PRSCONTROL,{key}" return self.run(command, **kwargs) - def prscontrol(self, key="", **kwargs): - """Specifies whether to include pressure load stiffness in the element + def pscontrol(self, option: str = "", key: str = "", **kwargs): + r"""Enables or disables shared-memory parallel operations. + + Mechanical APDL Command: `PSCONTROL `_ - APDL Command: PRSCONTROL - stiffness formation. + **Command default:** + None. The command is ignored if issued with no arguments. Parameters ---------- - key - Pressure load stiffness key. In general, use the default setting. - Use a non-default setting only if you encounter convergence - difficulties. Pressure load stiffness is automatically included - when using eigenvalue buckling analyses (ANTYPE,BUCKLE), equivalent - to Key = INCP. For all other types of analyses, valid arguments for - Key are: - - NOPL - Pressure load stiffness not included for any elements. - - (blank) (default) - Include pressure load stiffness for elements SURF153, SURF154, SURF156, - SURF159, SHELL181, PLANE182, PLANE183, SOLID185, - SOLID186, SOLID187, SOLSH190, BEAM188, BEAM189, - FOLLW201, SHELL208, SHELL209, SOLID272, SOLID273, - SHELL281, SOLID285, PIPE288, PIPE289, and - ELBOW290. Do not include pressure load stiffness - for elements SOLID65. - - INCP - Pressure load stiffness included for all of the default elements listed above - and SOLID65. + option : str + Specify the operations for which you intend to enable/disable parallel behavior: + + * ``ALL`` - Enable/disable parallel for all areas (default). + + * ``PREP`` - Enable/disable parallel during preprocessing ( :ref:`prep7` ). + + * ``SOLU`` - Enable/disable parallel during solution ( :ref:`slashsolu` ). + + * ``FORM`` - Enable/disable parallel during element matrix generation. + + * ``SOLV`` - Enable/disable parallel during equation solver. + + * ``RESU`` - Enable/disable parallel during element results calculation. + + * ``POST`` - Enable/disable parallel during postprocessing ( :ref:`post1` and :ref:`post26` ). + + * ``STAT`` - List parallel operations that are enabled/disabled. + + key : str + Option control key. Used for all ``Option`` values except STAT. + + * ``ON`` - Enable parallel operation. + + * ``OFF`` - Disable parallel operation. Notes ----- - This command is rarely needed. The default settings are recommended for - most analyses. + Use this command in shared-memory parallel operations. + + This command is useful when you encounter minor discrepancies in a nonlinear solution when using + different numbers of processors. A parallel operation applied to the element matrix generation can + produce a different nonlinear solution with a different number of processors. Although the nonlinear + solution converges to the same nonlinear tolerance, the minor discrepancy created may not be + desirable for consistency. + + Enabling/disabling parallel behavior for the solution ( ``Option`` = SOLU) supersedes the + activation/deactivation of parallel behavior for element matrix generation (FORM), equation solver + (SOLV), and element results calculation (RESU). + + The SOLV option supports only the sparse direct and PCG solvers ( :ref:`eqslv`,SPARSE or PCG). No + other solvers are supported. + + This command applies only to shared-memory architecture. It does not apply to distributed-memory + parallel processing. """ - command = f"PRSCONTROL,{key}" + command = f"PSCONTROL,{option},{key}" return self.run(command, **kwargs) - def pscontrol(self, option="", key="", **kwargs): - """Enables or disables shared-memory parallel operations. + def psolve(self, lab: str = "", **kwargs): + r"""Directs the program to perform a partial solution. - APDL Command: PSCONTROL + Mechanical APDL Command: `PSOLVE `_ Parameters ---------- - option - Specify the operations for which you intend to enable/disable - parallel behavior: + lab : str + Valid labels defining the solution step. All characters are required: - ALL - Enable/disable parallel for all areas (default). + * ``EIGDAMP`` - Calculates the eigenvalues and eigenvectors using the damped eigensolver. Requires + :file:`Jobname.FULL` from :ref:`modopt`,UNSYM or :ref:`modopt`,DAMP options. Produces + :file:`JobnameMODE`. - PREP - Enable/disable parallel during preprocessing (/PREP7). + * ``EIGQRDA`` - Calculates eigenvalues and eigenvectors using the QR damped eigensolver. Requires + :file:`Jobname.EMAT` from :ref:`modopt`,QRDAMP option. Produces :file:`JobnameMODE`. - SOLU - Enable/disable parallel during solution (/SOLU). + * ``EIGEXP`` - Expands the eigenvector solution. Requires :file:`Jobname.ESAV` and + :file:`Jobname.MODE`. Produces :file:`JobnameRST`. - FORM - Enable/disable parallel during element matrix generation. + * ``EIGLANB`` - Calculates the eigenvalues and eigenvectors using Block Lanczos. Requires + :file:`Jobname.EMAT` from :ref:`modopt`,LANB option. Produces :file:`JobnameMODE`. - SOLV - Enable/disable parallel during equation solver. + * ``EIGLANPCG`` - Calculates the eigenvalues and eigenvectors using PCG Lanczos. Requires + :file:`Jobname.EMAT` from :ref:`modopt`,LANPCG option. Produces :file:`JobnameMODE`. - RESU - Enable/disable parallel during element results calculation. + * ``EIGSNODE`` - Calculates the eigenvalues and eigenvectors using the Supernode method. Requires + :file:`Jobname.EMAT` from :ref:`modopt`,SNODE option. Produces :file:`Jobname.MODE`. (See the + :ref:`modopt` command for more information on the SNODE modal solver.) - POST - Enable/disable parallel during postprocessing (/POST1 and /POST26). + * ``EIGUNSYM`` - Calculates the eigenvalues and eigenvectors using the unsymmetric eigensolver. + Requires :file:`Jobname.EMAT` from :ref:`modopt`,UNSYM or :ref:`modopt`,DAMP options. Produces + :file:`JobnameMODE`. - STAT - List parallel operations that are enabled/disabled. + * ``ELFORM`` - Creates the element matrices. Produces :file:`Jobname.EMAT` and :file:`JobnameESAV`. + If you want to include prestress effects ( :ref:`pstres`,ON) from a previous prestress analysis, the + ELFORM option requires the :file:`Jobname.EMAT` and :file:`Jobname.ESAV` files generated by that + analysis. - key - Option control key. Used for all Option values except STAT. + Notes + ----- - ON - Enable parallel operation. + .. _PSOLVE_notes: - OFF - Disable parallel operation. + Directs the program to perform a partial solution (that is, one step of an analysis sequence). + Predefined analysis types ( :ref:`antype` ) perform a defined subset of these solution steps in a + predefined sequence. You can use the partial-solution procedure to repeat a certain step of an + analysis or to restart an analysis. - Notes - ----- - Use this command in shared-memory parallel operations. + Not all steps are valid for all analysis types. The order of the steps may vary depending on the + result you desire. See the `Basic Analysis Guide + `_ for a + description of how to perform partial and predefined + solutions. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + In a cyclic symmetry analysis, :ref:`psolve`,EIGLANB or :ref:`psolve`,EIGLANPCG performs the modal + analysis at multiple load steps, one for each nodal-diameter specified via the :ref:`cycopt` + command. In addition, the eigenvector solution is expanded at each nodal-diameter solution, + eliminating the need for a separate expansion pass ( :ref:`psolve`,EIGEXP). + + If :file:`Jobname.EMAT` is required, run the prior analysis with :ref:`ematwrite`,YES to ensure that + a :file:`Jobname.EMAT` is generated. - This command is useful when you encounter minor discrepancies in a - nonlinear solution when using different numbers of processors. A - parallel operation applied to the element matrix generation can produce - a different nonlinear solution with a different number of processors. - Although the nonlinear solution converges to the same nonlinear - tolerance, the minor discrepancy created may not be desirable for - consistency. + Distributed-Memory Parallel (DMP) Restriction Only the EIGLANB, and EIGLANPCG options on this + command are supported in a DMP solution. - Enabling/disabling parallel behavior for the solution (Option = SOLU) - supersedes the activation/deactivation of parallel behavior for element - matrix generation (FORM), equation solver (SOLV), and element results - calculation (RESU). + .. warning:: - The SOLV option supports only the sparse direct and PCG solvers - (EQSLV,SPARSE or PCG). No other solvers are supported. + This command is archived in the latest version of the software. - This command applies only to shared-memory architecture. It does not - apply to the Distributed ANSYS product. """ - command = f"PSCONTROL,{option},{key}" + command = f"PSOLVE,{lab}" return self.run(command, **kwargs) - def rate(self, option="", **kwargs): - """Specifies whether the effect of creep strain rate will be used in the + def rate(self, option: str = "", **kwargs): + r"""Specifies whether the effect of creep strain rate will be used in the solution of a load step. - APDL Command: RATE - solution of a load step. + Mechanical APDL Command: `RATE `_ Parameters ---------- - option + option : str Activates implicit creep analysis. - 0 or OFF - No implicit creep analysis. This option is the default. + * ``0 or OFF`` - No implicit creep analysis. This option is the default. - 1 or ON - Perform implicit creep analysis. + * ``1 or ON`` - Perform implicit creep analysis. Notes ----- - Set Option = 1 (or ON) to perform an implicit creep analysis (TB,CREEP - with TBOPT : 1). For viscoplasticity/creep analysis, Option specifies - whether or not to include the creep calculation in the solution of a - load step. If Option = 1 (or ON), ANSYS performs the creep calculation. - Set an appropriate time for solving the load step via a TIME,TIME - command. + + .. _RATE_notes: + + Set ``Option`` = 1 (or ON) to perform an implicit creep analysis ( :ref:`tb`,CREEP with ``TBOPT`` + :math:`equation not available` 1). For viscoplasticity/creep analysis, ``Option`` specifies + whether or not to include the creep calculation in the solution of a load step. If ``Option`` = 1 + (or ON), the program performs the creep calculation. Set an appropriate time for solving the load + step via a :ref:`time`, ``TIME`` command. + + **Product Restrictions** + + .. _RATE_extranote1: + + This command works only when modeling implicit creep with either von Mises or Hill potentials. + + When modeling implicit creep with von Mises potential, you can use the following elements: + ``LINK180``, ``SHELL181``, ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, ``SOLID187``, + ``SOLID272``, ``SOLID273``, ``SOLID285``, ``SOLSH190``, ``BEAM188``, ``BEAM189``, ``SHELL208``, + ``SHELL209``, ``REINF264``, ``SHELL281``, and ``ELBOW290``. + + When modeling anisotropic creep ( :ref:`tb`,CREEP with :ref:`tb`,HILL), you can also use the + following elements: ``LINK180``, ``SHELL181``, ``PLANE182``, ``PLANE183``, ``SOLID185``, + ``SOLID186``, ``SOLID187``, ``BEAM188``, ``BEAM189``, ``SOLSH190``, ``SHELL208``, ``SHELL209``, + ``REINF264``, ``REINF265``, ``SOLID272``, ``SOLID273``, ``SHELL281``, ``SOLID285``, ``PIPE288``, + ``PIPE289``, and ``ELBOW290``. """ command = f"RATE,{option}" return self.run(command, **kwargs) - def resvec(self, key="", **kwargs): - """Calculates or includes residual vectors. + def resvec(self, keyvect: str = "", keyresp: str = "", **kwargs): + r"""Calculates or includes residual vectors or residual responses - APDL Command: RESVEC + Mechanical APDL Command: `RESVEC `_ + + **Command default:** + No residual quantities are calculated or included in the analysis. Parameters ---------- - key + keyvect : str Residual vector key: - OFF - Do not calculate or include residual vectors. This option is the default. + * ``OFF`` - Do not calculate or include residual vectors (default). - ON - Calculate or include residual vectors. + * ``ON`` - Calculate or include residual vectors. - Notes - ----- - In a modal analysis, the RESVEC command calculates residual vectors. In - a mode-superposition transient dynamic, mode-superposition harmonic, - PSD or spectrum analysis, the command includes residual vectors. - - In a component mode synthesis (CMS) generation pass, the RESVEC command - calculates one residual vector which is included in the normal modes - basis used in the transformation matrix. It is supported for the three - available CMS methods. RESVEC,ON can only be specified in the first - load step of a generation pass and is ignored if issued at another load - step. + keyresp : str + Residual response key: - If rigid-body modes exist, pseudo-constraints are required for the - calculation. Issue the D,,,SUPPORT command to specify only the minimum - number of pseudo-constraints necessary to prevent rigid-body motion. + * ``OFF`` - Do not calculate or include residual responses (default). - For more information about residual vector formulation, see Residual - Vector Method in the Mechanical APDL Theory Reference. + * ``ON`` - Calculate or include residual responses. + + Notes + ----- + In a `modal analysis + `_, the + :ref:`resvec` command calculates residual vectors (or responses). In a `mode-superposition transient + `_, + `mode-superposition harmonic + `_, + PSD or `spectrum + `_ analysis, the + command includes residual vectors. The command must be issued during the first modal solve. + + In the expansion pass of a mode-superposition transient or mode-superposition harmonic analysis, the + command includes residual responses. + + In a component mode synthesis (CMS) `generation pass + `_, + the :ref:`resvec` command calculates one residual vector which is included in the normal modes basis + used in the transformation matrix. It is supported for the three available `CMS methods + `_. + :ref:`resvec`,ON can only be specified in the first load step of a generation pass and is ignored if + issued at another load step. + + If rigid-body modes exist, pseudo-constraints are required for the calculation. Issue the + :ref:`d`,,,SUPPORT command to specify only the minimum number of pseudo-constraints necessary to + prevent rigid-body motion. + + Both residual vector and residual response approaches cannot be used in the same analysis. + + For more information about residual vector or residual response formulation, see `Residual Vector + Method `_ + `Residual Response Method + `_ """ - command = f"RESVEC,{key}" + command = f"RESVEC,{keyvect},,,,{keyresp}" return self.run(command, **kwargs) - def rstoff(self, lab="", offset="", **kwargs): - """Offsets node or element IDs in the FE geometry record. + def rstoff(self, lab: str = "", offset: str = "", **kwargs): + r"""Offsets node or element IDs in the FE geometry record. + + Mechanical APDL Command: `RSTOFF `_ - APDL Command: RSTOFF + **Command default:** + + .. _RSTOFF_default: + + Issuing the :ref:`rstoff` command with no specified argument values applies no offsets. Parameters ---------- - lab + lab : str The offset type: - NODE - Offset the node IDs. + * ``NODE`` - Offset the node IDs. - ELEM - Offset the element IDs. + * ``ELEM`` - Offset the element IDs. - offset - A positive integer value specifying the offset value to apply. The - value must be greater than the number of nodes or elements in the - existing superelement results file. + offset : str + A positive integer value specifying the offset value to apply. The value must be greater than + the number of nodes or elements in the existing superelement results file. Notes ----- - The RSTOFF command offsets node or element IDs in the FE geometry - record saved in the .rst results file. Use the command when expanding - superelements in a bottom-up substructuring analysis (where each - superelement is generated individually in a generation pass, and all - superelements are assembled together in the use pass). - - With appropriate offsets, you can write results files with unique node - or element IDs and thus display the entire model even if the original - superelements have overlapping element or node ID sets. (Such results - files are incompatible with the .db database file saved at the + The :ref:`rstoff` command offsets node or element IDs in the FE geometry record saved in the + :file:`.rst` results file. Use the command when expanding superelements in a bottom-up + substructuring analysis (where each superelement is generated individually in a `generation pass + `_, + and all superelements are assembled together in the `use pass + `_ + ). + + With appropriate offsets, you can write results files with unique node or element IDs and thus + display the entire model even if the original superelements have overlapping element or node ID + sets. (Such results files are incompatible with the :file:`.db` database file saved at the generation pass.) - The offset that you specify is based on the original superelement node - or element numbering, rather than on any offset specified via a SESYMM - or SETRAN command. When issuing an RSTOFF command, avoid specifying an - offset that creates conflicting node or element numbers for a - superelement generated via a SESYMM or SETRAN command. + The offset that you specify is based on the original superelement node or element numbering, rather + than on any offset specified via a :ref:`sesymm` or :ref:`setran` command. When issuing an + :ref:`rstoff` command, avoid specifying an offset that creates conflicting node or element numbers + for a superelement generated via a :ref:`sesymm` or :ref:`setran` command. + + If you issue the command to set non-zero offsets for node or element IDs, you must bring the + geometry into the database via the :ref:`set` command so that Mechanical APDL can display the + results. + Specify appropriate offsets to avoid overlapping node or element IDs with other superelement results + files. + + The command is valid only in the first load step of a `superelement expansion pass + `_. - If you issue the command to set non-zero offsets for node or element - IDs, you must bring the geometry into the database via the SET command - so that ANSYS can display the results. You must specify appropriate - offsets to avoid overlapping node or element IDs with other - superelement results files. - The command is valid only in the first load step of a superelement - expansion pass. """ command = f"RSTOFF,{lab},{offset}" return self.run(command, **kwargs) - def scopt(self, tempdepkey="", **kwargs): - """Specifies System Coupling options. + def scopt(self, tempdepkey: str = "", mappingkey: str = "", **kwargs): + r"""Specifies System Coupling options. - APDL Command: SCOPT + Mechanical APDL Command: `SCOPT `_ Parameters ---------- - tempdepkey - Temperature-dependent behavior key based on the convection - coefficient: + tempdepkey : str + Temperature-dependent behavior key based on the convection coefficient: - * ``"YES"`` : A negative convection coefficient, -N, is - assumed to be a function of temperature and is determined - from the HF property table for material N (MP command). This - is the default. + * ``YES`` - A negative convection coefficient, - ``N``, is assumed to be a function of temperature + and is determined from the HF property table for material ``N`` ( :ref:`mp` command). This is the + default behavior. - * ``"NO"`` : A negative convection coefficient, -N, is used as - is in the convection calculation. + * ``NO`` - A negative convection coefficient, - ``N``, is used as is in the convection calculation. + + mappingkey : str + Controls whether midside nodes of higher-order elements are used for mapping on System Coupling + interfaces: + + * ``YES`` - Both corner and midside nodes are used (default). + + * ``NO`` - Only corner nodes are used. Notes ----- - By default in the Mechanical APDL program, a negative convection - coefficient value triggers temperature-dependent behavior. In - System Coupling, and in some one-way CFD to Mechanical APDL - thermal simulations, it is desirable to allow convection - coefficients to be used as negative values. To do so, issue the - command ``scopt("NO")``. + + .. _SCOPT_notes: + + By default in the Mechanical APDL program, a negative convection coefficient value triggers + temperature- + dependent behavior. In some one-way CFD to Mechanical APDL thermal simulations, it is desirable to + allow + convection coefficients to be used as negative values. To do so, issue the command :ref:`scopt`,NO. """ - return self.run(f"SCOPT,{tempdepkey}", **kwargs) + command = f"SCOPT,{tempdepkey},{mappingkey}" + return self.run(command, **kwargs) - def seexp(self, sename="", usefil="", imagky="", expopt="", **kwargs): - """Specifies options for the substructure expansion pass. + def seexp( + self, + sename: str = "", + usefil: str = "", + imagky: str = "", + expopt: str = "", + **kwargs, + ): + r"""Specifies options for the substructure expansion pass. - APDL Command: SEEXP + Mechanical APDL Command: `SEEXP `_ Parameters ---------- - sename - The name (case-sensitive) of the superelement matrix file created - by the substructure generation pass (Sename.SUB). Defaults to the - initial jobname File. If a number, it is the element number of the - superelement as used in the use pass. + sename : str + The name (case-sensitive) of the superelement matrix file created by the substructure generation + pass ( :file:`Sename.SUB` ). Defaults to the initial jobname :file:`File`. If a number, it is + the element number of the superelement as used in the use pass. + + usefil : str + The name of the file containing the superelement degree-of-freedom (DOF) solution created by the + substructure use pass ( :file:`Usefil.DSUB` ). - usefil - The name of the file containing the superelement degree-of-freedom - (DOF) solution created by the substructure use pass (Usefil.DSUB). + imagky : str + Key to specify use of the imaginary component of the DOF solution. Applicable only if the use pass + is a harmonic ( :ref:`antype`,HARMIC) analysis: - imagky - Key to specify use of the imaginary component of the DOF solution. - Applicable only if the use pass is a harmonic (ANTYPE,HARMIC) - analysis: + * ``OFF`` - Use real component of DOF solution (default). - OFF - Use real component of DOF solution (default). + * ``ON`` - Use imaginary component of DOF solution. - ON - Use imaginary component of DOF solution. + If all solutions are to be expanded ( :ref:`numexp`,ALL), ``Imagky`` is ignored and both the real + and imaginary solutions are expanded. - expopt - Key to specify whether the superelement (ANTYPE,SUBSTR) expansion - pass (EXPASS,ON) should transform the geometry: + expopt : str + Key to specify whether the superelement ( :ref:`antype` ,SUBSTR) expansion pass ( :ref:`expass`,ON) should transform the geometry: - OFF - Do not transform node or element locations (default). + * ``OFF`` - Do not transform node or element locations (default). - ON - Transform node or element locations in the FE geometry record of the .rst - results file. + * ``ON`` - Transform node or element locations in the FE geometry record of the :file:`.rst` results + file. Notes ----- - Specifies options for the expansion pass of the substructure analysis - (ANTYPE,SUBSTR). If used in SOLUTION, this command is valid only - within the first load step. - - If you specify geometry transformation (Expopt = ON), you must retrieve - the transformation matrix (if it exists) from the specified .SUB file. - The command updates the nodal X, Y, and Z coordinates to represent the - transformed node locations. The Expopt option is useful when you want - to expand superelements created from other superelements (via SETRAN or - SESYMM commands). For more information, see Superelement Expansion in - Transformed Locations and Plotting or Printing Mode Shapes. - - This command is also valid in /PREP7. + + .. _SEEXP_notes: + + Specifies options for the expansion pass of the substructure analysis ( :ref:`antype`,SUBSTR). If + used in SOLUTION, this command is valid only within the first load step. + + If you specify geometry transformation ( ``Expopt`` = ON), you must retrieve the transformation + matrix (if it exists) from the specified :file:`.SUB` file. The command updates the nodal X, Y, and + Z coordinates to represent the transformed node locations. The ``Expopt`` option is useful when you + want to expand superelements created from other superelements (via :ref:`setran` or :ref:`sesymm` + commands). For more information, see and. + + + This command is also valid in :ref:`prep7`. """ command = f"SEEXP,{sename},{usefil},{imagky},{expopt}" return self.run(command, **kwargs) def seopt( self, - sename="", - sematr="", - sepr="", - sesst="", - expmth="", - seoclvl="", + sename: str = "", + sematr: int | str = "", + sepr: int | str = "", + sesst: int | str = "", + expmth: str = "", + seoclvl: str = "", + lpnamekey: str = "", **kwargs, ): - """Specifies substructure analysis options. + r"""Specifies substructure analysis options. - APDL Command: SEOPT + Mechanical APDL Command: `SEOPT `_ Parameters ---------- - sename - The name (case-sensitive, thirty-two character maximum) assigned to - the superelement matrix file. The matrix file will be named - Sename.SUB. This field defaults to Fname on the /FILNAME command. + sename : str + The name (case-sensitive, 32-character maximum) assigned to the :file:`.sub` superelement matrix + file. This field defaults to ``Fname`` on the :ref:`filname` command. - sematr + sematr : int or str Matrix generation key: - 1 - Generate stiffness (or conductivity) matrix (default). + * ``1`` - Generate stiffness (or conductivity) matrix (default). - 2 - Generate stiffness and mass (or conductivity and specific heat) matrices. + * ``2`` - Generate stiffness and mass (or conductivity and specific heat) matrices. - 3 - Generate stiffness, mass and damping matrices. + * ``3`` - Generate stiffness, mass and damping matrices. - sepr + sepr : int or str Print key: - 0 - Do not print superelement matrices or load vectors. + * ``0`` - Do not print superelement matrices or load vectors. - 1 - Print both load vectors and superelement matrices. + * ``1`` - Print both load vectors and superelement matrices. - 2 - Print load vectors but not matrices. + * ``2`` - Print load vectors but not matrices. - sesst - Stress stiffening key: + sesst : int or str + Stress-stiffening key: - 0 - Do not save space for stress stiffening in a later run. + * ``0`` - Do not save space for stress stiffening in a later run. - 1 - Save space for the stress stiffening matrix (calculated in a subsequent - generation run after the expansion pass). + * ``1`` - Save space for the stress stiffening matrix (calculated in a subsequent generation run + after the expansion pass). - expmth + expmth : str Expansion method for expansion pass: - BACKSUB - Save necessary factorized matrix files for backsubstitution during subsequent - expansion passes (default). This normally results in a - large usage of disk space + * ``BACKSUB`` - Save necessary factorized matrix files (for example, the :file:`.LN22` file) for + backsubstitution during the subsequent expansion passes (default). This normally results in a large + usage of disk space. + + * ``MODDIR`` - This is the same expansion method as BACKSUB, except that the static correction + vectors (see the first term of in the `Mechanical APDL Theory Reference `_) are stored on the :file:`.bclv` file instead of + the :file:`.LN22` file. This option is required when remote read-only file usage is used during the + first solution of the first restart of a generation pass (see the :ref:`moddir` command). + + * ``RESOLVE`` - Do not save factorized matrix files. Global stiffness matrix will be reformed during + expansion pass. This option provides an effective way to save disk space usage. This option cannot + be used if the use pass uses large deflections ( :ref:`nlgeom`,ON). + + * ``NONE`` - Do not save factorized matrix files. With this option, the expansion pass is not + possible when factorized matrix files are required. + + * ``BCLV`` - Do not save factorized matrix files. The static correction vectors (see the first term + of ) are stored in the :file:`.bclv` file. With this option, the expansion pass is not possible when + factorized matrix files are required. + + seoclvl : str + For the added-mass calculation, the ocean level to use when ocean waves ( :ref:`octype`,,WAVE) are present: - RESOLVE - Do not save factorized matrix files. Global stiffness matrix will be reformed - during expansion pass. This option provides an effective - way to save disk space usage. This option cannot be used - if the use pass uses large deflections (NLGEOM,ON). + * ``ATP`` - The ocean level at this point in time (default). - seoclvl - For the added-mass calculation, the ocean level to use when ocean - waves (OCTYPE,,WAVE) are present: + * ``MSL`` - The mean ocean level. - ATP - The ocean level at this point in time (default). + lpnamekey : str - MSL - The mean ocean level. + * ``ON`` - All files created during the generation pass are named using ``Sename``. + + * ``OFF`` - All files created during the generation pass are named using the :file:`Jobname` defined + for the analysis (see :ref:`filname` command) except for the :file:`.sub` file, which uses + ``Sename`` if specified (default). Notes ----- - The SEOPT command specifies substructure analysis options - (ANTYPE,SUBSTR). If used during solution, the command is valid only - within the first load step. - - When ocean waves (OCTYPE,,WAVE) are present, the SeOcLvL argument - specifies the ocean height or level to use for the added-mass - calculation, as the use-run analysis type is unknown during the - generation run. - - The expansion pass method RESOLVE is not supported with component mode - synthesis analysis (CMSOPT). ExpMth is automatically set to BACKSUB for - CMS analysis. The RESOLVE method invalidates the use of the NUMEXP - command. The RESOLVE method does not allow the computation of results - based on nodal velocity and nodal acceleration (damping force, inertial - force, kinetic energy, etc.) in the substructure expansion pass. + + .. _SEOPT_notes: + + :ref:`seopt` specifies substructure analysis options ( :ref:`antype`,SUBSTR). If used during + solution, the command is valid only within the first load step. + + When ocean waves ( :ref:`octype`,,WAVE) are present, the ``SeOcLvL`` argument specifies the ocean + height or level to use for the added-mass calculation, as the use-run analysis type is unknown + during the generation run. + + The expansion pass method RESOLVE is not supported with component mode synthesis analysis ( + :ref:`cmsopt` ). ``ExpMth`` is automatically set to BACKSUB for CMS analysis. The RESOLVE method + invalidates the use of the :ref:`numexp` command. The RESOLVE method does not allow the restarting + of the substructure generation pass and the computation of results based on nodal velocity and nodal + acceleration (damping force, inertial force, kinetic energy, etc.) in the substructure expansion + pass. + + If ``ExpMth`` = NONE or BCLV in a substructure analysis or component mode synthesis (CMS) analysis ( + :ref:`cmsopt` ) using the fixed-interface ( :ref:`cmsopt`,FIX) or free-interface ( :ref:`cmsopt` + ,FREE) methods, you cannot restart the generation pass or perform the expansion pass. (In CMS + analyses using those methods, however, the expansion pass is possible when element-results + calculation is activated in the generation pass ( ``ELCALC`` = YES on :ref:`cmsopt` )). The + ``ExpMth`` argument is not required for CMS analysis using the residual-flexible free-interface + method ( :ref:`cmsopt`,RFFB). + + For linear perturbation substructure generation pass with multiple substructures, set ``LPnameKey`` + = ON to avoid copying files at the end of each generation pass with the :ref:`copy` command. For an + example with CMS analysis using the fixed-interface method, see. This command is also valid in PREP7. """ - command = f"SEOPT,{sename},{sematr},{sepr},{sesst},{expmth},{seoclvl}" + command = ( + f"SEOPT,{sename},{sematr},{sepr},{sesst},{expmth},{seoclvl},,{lpnamekey}" + ) return self.run(command, **kwargs) def snoption( self, - rangefact="", - blocksize="", - robustlev="", - compute="", - solve_info="", + rangefact: str = "", + blocksize: str = "", + robustlev: str = "", + compute: str = "", + solve_info: str = "", **kwargs, ): - """Specifies Supernode (SNODE) eigensolver options. + r"""Specifies Supernode (SNODE) eigensolver options. + + Mechanical APDL Command: `SNOPTION `_ + + **Command default:** - APDL Command: SNOPTION + .. _SNOPTION_default: + + ``RangeFact`` = 2.0. ``BlockSize`` is set to min( ``NMODE``,40), where ``NMODE`` is the number of + modes to be computed as set on the :ref:`modopt` command. ``RobustLev`` = 0. ``Compute`` = BOTH. + Additional output is not printed ( ``Solve_Info`` = OFF). Parameters ---------- - rangefact - Factor used to control the range of eigenvalues computed for each - supernode. The value of RangeFact must be a number between 1.0 and - 5.0. By default the RangeFact value is set to 2.0, which means that - all eigenvalues between 0 and ``2*FREQE`` are computed for each - supernode (where FREQE is the upper end of the frequency range of - interest as specified on the MODOPT command). As the RangeFact - value increases, the eigensolution for the SNODE solver becomes - more accurate and the computational time increases. - - blocksize - BlockSize to be used when computing the final eigenvectors. The - value of Blocksize must be either MAX or a number between 1 and - NMODE, where NMODE is the number of modes to be computed as set on - the MODOPT command. Input a value of MAX to force the algorithm to - allocate enough memory to hold all of the final eigenvectors in - memory and, therefore, only read through the file containing the - supernode eigenvectors once. Note that this setting is ONLY - recommended when there is sufficient physical memory on the machine - to safely hold all of the final eigenvectors in memory. - - robustlev - Parameter used to control the robustness of the SNODE eigensolver. - The value of RobustLev must be a number between 0 and 10. Lower - values of RobustLev allow the eigensolver to run in the most - efficient manner for optimal performance. Higher values of - RobustLev often slow down the performance of the eigensolver, but - can increase the robustness; this may be desirable if a problem is - detected with the eigensolver or its eigensolution. - - compute - Key to control which computations are performed by the Supernode - eigensolver: - - EVALUE - The eigensolver computes only the eigenvalues. - - EVECTOR - The eigensolver computes only the eigenvectors - (must be preceded by a modal analysis where the - eigenvalues were computed using the Supernode - eigensolver). - - BOTH - The eigensolver computes both the eigenvalues and - eigenvectors in the same pass (default). - - solve_info + rangefact : str + Factor used to control the range of eigenvalues computed for each supernode. The value of ``RangeFact`` must be a number between 1.0 and 10.0. By default the ``RangeFact`` value is set to 2.0, which means that all eigenvalues between 0 and 2\* ``FREQE`` are computed for each supernode (where ``FREQE`` is the upper end of the frequency range of interest as specified on the :ref:`modopt` command). As the ``RangeFact`` value increases, the eigensolution for the SNODE solver becomes more accurate and the computational time increases. + + blocksize : str + ``BlockSize`` to be used when computing the final eigenvectors. The value of ``Blocksize`` must + be either MAX or a number between 1 and ``NMODE``, where ``NMODE`` is the number of modes to be + computed as set on the :ref:`modopt` command. Input a value of MAX to force the algorithm to + allocate enough memory to hold all of the final eigenvectors in memory and, therefore, only read + through the file containing the supernode eigenvectors once. Note that this setting is ONLY + recommended when there is sufficient physical memory on the machine to safely hold all of the + final eigenvectors in memory. + + robustlev : str + Parameter used to control the robustness of the SNODE eigensolver. The value of ``RobustLev`` + must be a number between 0 and 10. Lower values of ``RobustLev`` allow the eigensolver to run in + the most efficient manner for optimal performance. Higher values of ``RobustLev`` often slow + down the performance of the eigensolver, but can increase the robustness; this may be desirable + if a problem is detected with the eigensolver or its eigensolution. + + compute : str + Key to control which computations are performed by the Supernode eigensolver: + + * ``EVALUE`` - The eigensolver computes only the eigenvalues. + + * ``EVECTOR`` - The eigensolver computes only the eigenvectors (must be preceded by a modal analysis + where the eigenvalues were computed using the Supernode eigensolver). + + * ``BOTH`` - The eigensolver computes both the eigenvalues and eigenvectors in the same pass + (default). + + solve_info : str Solver output option: - OFF - Turns off additional output printing from the - Supernode eigensolver (default). + * ``OFF`` - Turns off additional output printing from the Supernode eigensolver (default). - PERFORMANCE - Turns on additional output printing from the - Supernode eigensolver, including a - performance summary and a summary of file - I/O for the Supernode - eigensolver. Information on memory usage - during assembly of the global matrices (that - is, creation of the Jobname.FULL file) is - also printed with this option. + * ``PERFORMANCE`` - Turns on additional output printing from the Supernode eigensolver, including a + performance summary and a summary of file I/O for the Supernode eigensolver. Information on memory + usage during assembly of the global matrices (that is, creation of the :file:`Jobname.FULL` file) is + also printed with this option. Notes ----- - This command specifies options for the Supernode (SNODE) - eigensolver. - - Setting RangeFact to a value greater than 2.0 will improve the - accuracy of the computed eigenvalues and eigenvectors, but - will often increase the computing time of the SNODE - eigensolver. Conversely, setting RangeFact to a value less - than 2.0 will deteriorate the accuracy of the computed - eigenvalues and eigenvectors, but will often speedup the - computing time of the SNODE eigensolver. The default value of - 2.0 has been set as a good blend of accuracy and performance. - - The SNODE eigensolver reads the eigenvectors and related - information for each supernode from a file and uses that - information to compute the final eigenvectors. For each - eigenvalue/eigenvector requested by the user, the program must - do one pass through the entire file that contains the - supernode eigenvectors. By choosing a BlockSize value greater - than 1, the program can compute BlockSize number of final - eigenvectors for each pass through the file. Therefore, - smaller values of BlockSize result in more I/O, and larger - values of BlockSize result in less I/O. Larger values of - BlockSize also result in significant additional memory usage, - as BlockSize number of final eigenvectors must be stored in - memory. The default Blocksize of min(NMODE,40) is normally a - good choice to balance memory and I/O usage. - - The RobustLev field should only be used when a problem is - detected with the accuracy of the final solution or if the - Supernode eigensolver fails while computing the - eigenvalues/eigenvectors. Setting RobustLev to a value greater - than 0 will cause the performance of the eigensolver to - deteriorate. If the performance deteriorates too much or if - the eigensolver continues to fail when setting the RobustLev - field to higher values, then switching to another eigensolver - such as Block Lanczos or PCG Lanczos is recommended. - - Setting Compute = EVALUE causes the Supernode eigensolver to - compute only the requested eigenvalues. During this process a - Jobname.SNODE file is written; however, a Jobname.MODE file is - not written. Thus, errors will likely occur in any downstream - computations that require the Jobname.MODE file (for example, - participation factor computations, mode superpostion - transient/harmonic analysis, PSD analysis). Setting Compute = - EVECTOR causes the Supernode eigensolver to compute only the - corresponding eigenvectors. The Jobname.SNODE file and the - associated Jobname.FULL file are required when requesting - these eigenvectors. In other words, the eigenvalues must have - already been computed for this model before computing the - eigenvectors. This field can be useful in order to separate - the two steps (computing eigenvalues and computing - eigenvectors). + + .. _SNOPTION_notes: + + This command specifies options for the Supernode (SNODE) eigensolver. + + Setting ``RangeFact`` to a value between 2.0 and 10.0 will improve the accuracy of the computed + eigenvalues and eigenvectors, but will often increase the computing time of the SNODE eigensolver. + Conversely, setting ``RangeFact`` to a value less than 2.0 will deteriorate the accuracy of the + computed eigenvalues and eigenvectors, but will often speed up the computing time of the SNODE + eigensolver. The default value of 2.0 has been set as a good blend of accuracy and performance. If + the model has rigid body modes, setting ``RangeFact`` higher than 2 is recommended to achieve better + solution accuracy for the lower flexible modes. + + The SNODE eigensolver reads the eigenvectors and related information for each supernode from a file + and uses that information to compute the final eigenvectors. For each eigenvalue/eigenvector + requested by the user, the program must do one pass through the entire file that contains the + supernode eigenvectors. By choosing a ``BlockSize`` value greater than 1, the program can compute + ``BlockSize`` number of final eigenvectors for each pass through the file. Therefore, smaller values + of ``BlockSize`` result in more I/O, and larger values of ``BlockSize`` result in less I/O. Larger + values of ``BlockSize`` also result in significant additional memory usage, as ``BlockSize`` number + of final eigenvectors must be stored in memory. The default ``Blocksize`` of min( ``NMODE``,40) is + normally a good choice to balance memory and I/O usage. + + The ``RobustLev`` field should only be used when a problem is detected with the accuracy of the + final solution or if the Supernode eigensolver fails while computing the eigenvalues/eigenvectors. + Setting ``RobustLev`` to a value greater than 0 will cause the performance of the eigensolver to + deteriorate. If the performance deteriorates too much or if the eigensolver continues to fail when + setting the ``RobustLev`` field to higher values, then switching to another eigensolver such as + Block Lanczos or PCG Lanczos is recommended. + + Setting ``Compute`` = EVALUE causes the Supernode eigensolver to compute only the requested + eigenvalues. During this process a :file:`Jobname.SNODE` file is written; however, a + :file:`Jobname.MODE` file is not written. Thus, errors will likely occur in any downstream + computations that require the :file:`Jobname.MODE` file (for example, participation factor + computations, mode superpostion transient/harmonic analysis, PSD analysis). Setting ``Compute`` = + EVECTOR causes the Supernode eigensolver to compute only the corresponding eigenvectors. The + :file:`Jobname.SNODE` file and the associated :file:`Jobname.FULL` file are required when requesting + these eigenvectors. In other words, the eigenvalues must have already been computed for this model + before computing the eigenvectors. This field can be useful in order to separate the two steps + (computing eigenvalues and computing eigenvectors). + + For more information on the eigensolver's accuracy and a discussion of its known limitations, see in + the `Mechanical APDL Theory Reference + `_ """ command = ( f"SNOPTION,{rangefact},{blocksize},{robustlev},{compute},,{solve_info}" ) return self.run(command, **kwargs) - def solve(self, action="", **kwargs): - """Starts a solution. + def solve(self, action: str = "", **kwargs): + r"""Starts a solution. - APDL Command: SOLVE + Mechanical APDL Command: `SOLVE `_ Parameters ---------- - action - Action to be performed on solve (used only for linear perturbation - analyses). + action : str + Action to be performed on solve (used only for linear perturbation analyses). - ELFORM - Reform all appropriate element matrices in the first phase of a linear - perturbation analysis. + * ``ELFORM`` - Reform all appropriate element matrices in the first phase of a linear perturbation + analysis. Notes ----- - Starts the solution of one load step of a solution sequence based on - the current analysis type and option settings. Use Action = ELFORM only - in the first phase of a linear perturbation analysis. + + .. _SOLVE_notes: + + Starts the solution of one load step of a solution sequence based on the current analysis type and + option settings. Use ``Action`` = ELFORM only in the first phase of a `linear perturbation analysis + `_. """ command = f"SOLVE,{action}" return self.run(command, **kwargs) def stabilize( - self, key="", method="", value="", substpopt="", forcelimit="", **kwargs + self, + key: str = "", + method: str = "", + value: str = "", + substpopt: str = "", + forcelimit: str = "", + recalcdamp: str = "", + **kwargs, ): - """Activates stabilization for all elements that support nonlinear + r"""Activates stabilization for all elements that support nonlinear stabilization. - APDL Command: STABILIZE - stabilization. + Mechanical APDL Command: `STABILIZE `_ Parameters ---------- - key + key : str Key for controlling nonlinear stabilization: - OFF - Deactivate stabilization. This value is the default. + * ``OFF`` - Deactivate stabilization (default). - CONSTANT - Activate stabilization. The energy-dissipation ratio or damping factor remains - constant during the load step. + * ``CONSTANT`` - Activate stabilization. The energy-dissipation ratio or damping factor remains + constant during the load step. - REDUCE - Activate stabilization. The energy-dissipation ratio or damping factor is - reduced linearly to zero at the end of the load step from - the specified or calculated value. + * ``REDUCE`` - Activate stabilization. The energy-dissipation ratio or damping factor is reduced + linearly to zero at the end of the load step from the specified or calculated value. - method + method : str The stabilization-control method: - ENERGY - Use the energy-dissipation ratio as the control. This value is the default - when Key ≠ OFF. + * ``ENERGY`` - Use the energy-dissipation ratio as the control. This value is the default when + ``Key`` ≠ OFF. - DAMPING - Use the damping factor as the control. + * ``DAMPING`` - Use the damping factor as the control. - value - The energy-dissipation ratio (Method = ENERGY) or damping factor - (Method = DAMPING). This value must be greater than 0 when Method = - ENERGY or Method = DAMPING. When Method = ENERGY, this value is - usually a number between 0 and 1. + value : str + The energy-dissipation ratio ( ``Method`` = ENERGY) or damping factor ( ``Method`` = DAMPING). + This value must be greater than 0 when ``Method`` = ENERGY or ``Method`` = DAMPING. When + ``Method`` = ENERGY, this value is usually a number between 0 and 1. - substpopt + substpopt : str Option for the first substep of the load step: - NO - Stabilization is not activated for the first substep even when it does not - converge after the minimal allowed time increment is reached. - This value is the default when Key ≠ OFF. + * ``NO`` - Stabilization is not activated for the first substep even when it does not converge after + the minimal allowed time increment is reached. This value is the default when ``Key`` ≠ OFF. - MINTIME - Stabilization is activated for the first substep if it still does not converge - after the minimal allowed time increment is reached. + * ``MINTIME`` - Stabilization is activated for the first substep if it still does not converge after + the minimal allowed time increment is reached. - ANYTIME - Stabilization is activated for the first substep. Use this option if - stabilization was active for the previous load step via - Key = CONSTANT. + * ``ANYTIME`` - Stabilization is activated for the first substep. Use this option if stabilization + was active for the previous load step via ``Key`` = CONSTANT. - forcelimit - The stabilization force limit coefficient, such that 0 < FORCELIMIT - < 1. The default value is 0.2. To omit a stabilization force check, - set this value to 0. + forcelimit : str + The stabilization force limit coefficient, such that 0 < ``FORCELIMIT`` < 1. The default value + is 0.2. To omit a stabilization force check, set this value to 0. + + recalcdamp : str + Key for controlling damping recalculation: + + * 0 - No recalculation of the damping factor (default). + * 1 - Recalculate the damping factor for the energy-based stabilization-control method. Notes ----- - Once issued, a STABILIZE command remains in effect until you reissue - the command. - - For the energy dissipation ratio, specify VALUE = 1.0e-4 if you have no - prior experience with the current model; if convergence problems are - still an issue, increase the value gradually. The damping factor is - mesh-, material-, and time-step-dependent; an initial reference value - from the previous run (such as a run with the energy-dissipation ratio - as input) should suggest itself. - - Exercise caution when specifying SubStpOpt = MINTIME or ANYTIME for the - first load step; ANSYS, Inc. recommends this option only for - experienced users. If stabilization was active for the previous load - step via Key = CONSTANT and convergence is an issue for the first - substep, specify SubStpOpt = ANYTIME. - - When the L2-norm of the stabilization force (CSRSS value) exceeds the - L2-norm of the internal force multiplied by the stabilization force - coefficient, ANSYS issues a message displaying both the stabilization - force norm and the internal force norm. The FORCELIMIT argument allows - you to change the default stabilization force coefficient (normally 20 - percent). - - This command stabilizes the degrees of freedom for current-technology - elements only. Other elements can be included in the FE model, but - their degrees of freedom are not stabilized. - - For more information about nonlinear stabilization, see Unstable - Structures in the Structural Analysis Guide. For additional tips that - can help you to achieve a stable final model, see Simplify Your Model - in the Structural Analysis Guide. + + .. _STABILIZE_notes: + + Once issued, a :ref:`stabilize` command remains in effect until you reissue the command. + + For the energy dissipation ratio, specify ``VALUE`` = 1.0e-4 if you have no prior experience with + the current model; if convergence problems are still an issue, increase the value gradually. The + damping factor is mesh-, material-, and time-step-dependent; an initial reference value from the + previous run (such as a run with the energy-dissipation ratio as input) should suggest itself. + + Exercise caution when specifying ``SubStpOpt`` = MINTIME or ANYTIME for the first load step; + Ansys, Inc. recommends this option only for experienced users. If stabilization was active + for the previous load step via ``Key`` = CONSTANT and convergence is an issue for the first substep, + specify ``SubStpOpt`` = ANYTIME. + + When the L2-norm of the stabilization force (CSRSS value) exceeds the L2-norm of the internal force + multiplied by the stabilization force coefficient, the program issues a message displaying both the + stabilization force norm and the internal force norm. The ``FORCELIMIT`` argument enables you to + change the default stabilization force coefficient (normally 20 percent). + + When using the energy-based stabilization-control method and ``RECALCDAMP`` = 1, the damping factor + is recalculated in the following cases: + + * In an analysis `restart + `_. + + * In a nonlinear adaptivity analysis in the substep following the remeshing substep. + + This command stabilizes the degrees of freedom for `current-technology elements + `_ + only. Other elements can be included in the FE model, but their degrees of freedom are not + stabilized. + + For more information about nonlinear stabilization, see `Unstable Structures + `_ + in the `Structural Analysis Guide + `_. """ - command = f"STABILIZE,{key},{method},{value},{substpopt},{forcelimit}" + command = ( + f"STABILIZE,{key},{method},{value},{substpopt},{forcelimit},{recalcdamp}" + ) return self.run(command, **kwargs) - def thexpand(self, key="", **kwargs): - """Enables or disables thermal loading + def thexpand(self, key: str = "", **kwargs): + r"""Enables or disables thermal loading - APDL Command: THEXPAND + Mechanical APDL Command: `THEXPAND `_ Parameters ---------- - key + key : str Activation key: - ON - Thermal loading is included in the load vector (default). + * ``ON`` - Thermal loading is included in the load vector (default). - OFF - Thermal loading is not included in the load vector. + * ``OFF`` - Thermal loading is not included in the load vector. Notes ----- - Temperatures applied in the analysis are used by default to evaluate - material properties and contribute to the load vector if the - temperature does not equal the reference temperature and a coefficient - of thermal expansion is specified. - - Use THEXPAND,OFF to evaluate the material properties but not contribute - to the load vector. This capability is particularly useful when - performing a harmonic analysis where you do not want to include - harmonically varying thermal loads. It is also useful in a modal - analysis when computing a modal load vector but excluding the thermal - load. - - This command is valid for all analysis types except linear perturbation - modal and linear perturbation harmonic analyses. For these two linear - perturbation analysis types, the program internally sets THEXPAND,OFF, - and it cannot be set to ON by using this command (THEXPAND,ON is - ignored). + + .. _THEXPAND_notes: + + Temperatures applied in the analysis are used by default to evaluate material properties and + contribute to the load vector if the temperature does not equal the reference temperature and a + coefficient of thermal expansion is specified. + + Use :ref:`thexpand`,OFF to evaluate the material properties but not contribute to the load vector. + This capability is particularly useful when performing a harmonic analysis where you do not want to + include harmonically varying thermal loads. It is also useful in a modal analysis when computing a + modal load vector but excluding the thermal load. + + This command is valid for all analysis types except linear perturbation modal and linear + perturbation harmonic analyses. For these two linear perturbation analysis types, the program + internally sets :ref:`thexpand`,OFF, and it cannot be set to ON by using this command ( + :ref:`thexpand`,ON is ignored). """ command = f"THEXPAND,{key}" return self.run(command, **kwargs) def thopt( self, - refopt="", - reformtol="", - ntabpoints="", - tempmin="", - tempmax="", - algo="", + refopt: str = "", + reformtol: str = "", + ntabpoints: str = "", + tempmin: str = "", + tempmax: str = "", + algo: int | str = "", **kwargs, ): - """Specifies nonlinear transient thermal solution options. + r"""Specifies nonlinear transient thermal solution options. - APDL Command: THOPT + Mechanical APDL Command: `THOPT `_ Parameters ---------- - refopt + refopt : str Matrix reform option. - FULL - Use the full Newton-Raphson solution option (default). All subsequent input - values are ignored. + * ``FULL`` - Use the full Newton-Raphson solution option (default). All subsequent input values are + ignored. - QUASI - Use a selective reform solution option based on REFORMTOL. + * ``QUASI`` - Use a selective reform solution option based on ``REFORMTOL``. - reformtol - Property change tolerance for Matrix Reformation (.05 default). The - thermal matrices are reformed if the maximum material property - change in an element (from the previous reform time) is greater - than the reform tolerance. Valid only when Refopt = QUASI. + reformtol : str + Property change tolerance for Matrix Reformation (.05 default). The thermal matrices are + reformed if the maximum material property change in an element (from the previous reform time) + is greater than the reform tolerance. Valid only when ``Refopt`` = QUASI. - ntabpoints - Number of points in Fast Material Table (64 default). Valid only - when Refopt = QUASI. + ntabpoints : str + Number of points in Fast Material Table (64 default). Valid only when ``Refopt`` = QUASI. - tempmin - Minimum temperature for Fast Material Table. Defaults to the - minimum temperature defined by the MPTEMP command for any material - property defined. Valid only when Refopt = QUASI. + tempmin : str + Minimum temperature for Fast Material Table. Defaults to the minimum temperature defined by the + :ref:`mptemp` command for any material property defined. Valid only when ``Refopt`` = QUASI. - tempmax - Maximum temperature for Fast Material Table. Defaults to the - maximum temperature defined by the MPTEMP command for any material - property defined. Valid only when Refopt = QUASI. + tempmax : str + Maximum temperature for Fast Material Table. Defaults to the maximum temperature defined by the + :ref:`mptemp` command for any material property defined. Valid only when ``Refopt`` = QUASI. - -- - Reserved field. - - algo + algo : int or str Specifies which solution algorithm to apply: - 0 - Multipass (default). + * ``0`` - Multipass (default). + + * ``1`` - Iterative. - 1 - Iterative. + Valid only when ``Refopt`` = QUASI. Notes ----- - The QUASI matrix reform option is supported by the ICCG, JCG, and - sparse solvers only (EQSLV). - For Refopt = QUASI: + .. _THOPT_notes: - Results from a restart may be different than results from a single run - because the stiffness matrices are always recreated in a restart run, - but may or may not be in a single run (depending on the behavior - resulting from the REFORMTOL setting). Additionally, results may differ - between two single runs as well, if the matrices are reformed as a - result of the REFORMTOL setting. + The QUASI matrix reform option is supported by the ICCG, JCG, PCG, and sparse solvers only ( + :ref:`eqslv` ). The Quasi method is an approximation to the FULL method and will not be as accurate + when the nonlinearity is strong. However, you can control the inaccuracy by using small time steps. - Midside node temperatures are not calculated if 20-node thermal solid - elements (SOLID90 or SOLID279) are used. + For ``Refopt`` = QUASI: - For more information, see Solution Algorithms Used in Transient Thermal - Analysis in the Thermal Analysis Guide. + * Results from a restart may be different than results from a single run because the stiffness + matrices are always recreated in a restart run, but may or may not be in a single run (depending + on the behavior resulting from the ``REFORMTOL`` setting). Additionally, results may differ + between two single runs as well, if the matrices are reformed as a result of the ``REFORMTOL`` + setting. + + For more information, see `Solution Algorithms Used in Transient Thermal Analysis + `_ + """ + command = f"THOPT,{refopt},{reformtol},{ntabpoints},{tempmin},{tempmax},,{algo}" + return self.run(command, **kwargs) + + def toffst(self, value: str = "", **kwargs): + r"""Specifies the temperature offset from absolute zero to zero. + + Mechanical APDL Command: `TOFFST `_ + + Parameters + ---------- + value : str + Degrees between absolute zero and zero of temperature system used (should be positive). + + Notes + ----- + + .. _TOFFST_notes: + + Specifies the difference (in degrees) between absolute zero and the zero of the temperature system + used. Absolute temperature values are required in evaluating certain expressions, such as for creep, + swelling, radiation heat transfer, ``MASS71``, etc. (The offset temperature is not used in + evaluating emissivity.) Examples are 460° for the Fahrenheit system and 273° for the Celsius system. + The offset temperature is internally included in the element calculations and does not affect the + temperature input or output. If used in SOLUTION, this command is valid only within the first load + step. + + This command is also valid in PREP7. """ - command = f"THOPT,{refopt},{reformtol},{ntabpoints},{tempmin},{tempmax},{algo}" + command = f"TOFFST,{value}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/birth_and_death.py b/src/ansys/mapdl/core/_commands/solution/birth_and_death.py index bd311f1a9f9..b7610678782 100644 --- a/src/ansys/mapdl/core/_commands/solution/birth_and_death.py +++ b/src/ansys/mapdl/core/_commands/solution/birth_and_death.py @@ -20,103 +20,100 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -from typing import Optional, Union - -from ansys.mapdl.core.mapdl_types import MapdlFloat - class BirthAndDeath: - def ealive(self, elem: str = "", **kwargs) -> Optional[str]: - """Reactivates an element (for the birth and death capability). - APDL Command: EALIVE + def ealive(self, elem: str = "", **kwargs): + r"""Reactivates an element (for the birth and death capability). + + Mechanical APDL Command: `EALIVE `_ Parameters ---------- - elem - Element to be reactivated: - - ALL - Reactivates all selected elements (ESEL). - - Comp - Specifies a component name. + elem : str + Element to be reactivated. If ALL, reactivate all selected elements ( :ref:`esel` ). 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``. To specify a table, enclose the + table name in percent signs (%), e.g. :ref:`ealive`,``tabname``. Notes ----- - Reactivates the specified element when the birth and death - capability is being used. An element can be reactivated only - after it has been deactivated (EKILL). - Reactivated elements have a zero strain (or thermal heat - storage, etc.) state. + .. _EALIVE_notes: + + Reactivates the specified element when the birth and death capability is being used. An element can + be reactivated only after it has been deactivated ( :ref:`ekill` ). - ANSYS, Inc. recommends using the element - deactivation/reactivation procedure for analyses involving - linear elastic materials only. Do not use element - deactivation/reactivation in analyses involving time- - dependent materials, such as viscoelasticity, viscoplasticity, - and creep analysis. + Reactivated elements have a zero strain (or thermal heat storage, etc.) state. + + The usage of tabular input is described in in the `Advanced Analysis Guide + `_. This command is also valid in PREP7. """ command = f"EALIVE,{elem}" return self.run(command, **kwargs) - def ekill(self, elem: Union[str, int] = "", **kwargs) -> Optional[str]: - """Deactivates an element (for the birth and death capability). + def ekill(self, elem: str = "", **kwargs): + r"""Deactivates an element (for the birth and death capability). - APDL Command: EKILL + Mechanical APDL Command: `EKILL `_ Parameters ---------- - elem - Element to be deactivated. If ALL, deactivate all - selected elements [ESEL]. A component name may also be - substituted for ELEM. + elem : str + Element to be deactivated. If ALL, deactivate all selected elements ( :ref:`esel` ). 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``. To specify a table, enclose the + table name in percent signs (%), e.g. :ref:`ekill`,``tabname``. Notes ----- - Deactivates the specified element when the birth and death - capability is being used. A deactivated element remains in - the model but contributes a near-zero stiffness (or - conductivity, etc.) value (ESTIF) to the overall matrix. Any - solution-dependent state variables (such as stress, plastic - strain, creep strain, etc.) are set to zero. Deactivated - elements contribute nothing to the overall mass (or - capacitance, etc.) matrix. - The element can be reactivated with the EALIVE command. + .. _EKILL_notes: + + Deactivates the specified element when the birth and death capability is being used. A deactivated + element remains in the model but contributes a near-zero stiffness (or conductivity, etc.) value ( + :ref:`estif` ) to the overall matrix. Any solution-dependent state variables (such as stress, + plastic strain, creep strain, etc.) are set to zero. Deactivated elements contribute nothing to the + overall mass (or capacitance, etc.) matrix, and do not generate a load vector (pressures, + convections, gravity, etc.). - ANSYS, Inc. recommends using element deactivation/reactivation - (EKILL/EALIVE) for linear elastic materials only. For all other - materials, validate the results carefully before using them. + The usage of tabular input is described in in the `Advanced Analysis Guide + `_. + + The element can be reactivated with the :ref:`ealive` command. This command is also valid in PREP7. """ command = f"EKILL,{elem}" return self.run(command, **kwargs) - def estif(self, kmult: MapdlFloat = "", **kwargs) -> Optional[str]: - """Specifies the matrix multiplier for deactivated elements. + def estif(self, kmult: str = "", **kwargs): + r"""Specifies the matrix multiplier for deactivated elements. - APDL Command: ESTIF + Mechanical APDL Command: `ESTIF `_ - Specifies the stiffness matrix multiplier for elements deactivated with - the EKILL command (birth and death). + **Command default:** - This command is also valid in PREP7. + .. _ESTIF_default: + + Use 1.0E-6 as the multiplier. Parameters ---------- - kmult - Stiffness matrix multiplier for deactivated elements (defaults to - 1.0E-6). + kmult : str + Stiffness matrix multiplier for deactivated elements (defaults to 1.0E-6). + + Notes + ----- - Examples - -------- - >>> mapdl.prep7() - >>> mapdl.estif(1E-8) - 'DEAD ELEMENT STIFFNESS MULTIPLIER= 0.10000E-07' + .. _ESTIF_notes: + Specifies the stiffness matrix multiplier for elements deactivated with the :ref:`ekill` command + (birth and death). + + This command is also valid in PREP7. """ command = f"ESTIF,{kmult}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/dynamic_options.py b/src/ansys/mapdl/core/_commands/solution/dynamic_options.py index 9e12aa400aa..1b1f3680592 100644 --- a/src/ansys/mapdl/core/_commands/solution/dynamic_options.py +++ b/src/ansys/mapdl/core/_commands/solution/dynamic_options.py @@ -22,1309 +22,1830 @@ class DynamicOptions: - def alphad(self, value="", **kwargs): - """Defines the mass matrix multiplier for damping. - APDL Command: ALPHAD + def alphad(self, value: str = "", **kwargs): + r"""Defines the mass matrix multiplier for damping. + + Mechanical APDL Command: `ALPHAD `_ Parameters ---------- - value + value : str Mass matrix multiplier for damping. Notes ----- - This command defines the mass matrix multiplier α used to form the - viscous damping matrix [C] = α[M] where [M] is the mass matrix. - Values of α may also be input as a material property (use the ALPD - label on the MP command). If ALPD is included, the ALPD value is added - to the ALPHAD value as appropriate (see Damping Matrices in the - Mechanical APDL Theory Reference). Damping is not used in the static - (ANTYPE,STATIC) or buckling (ANTYPE,BUCKLE) analyses. + .. _ALPHAD_notes: + + This command defines the mass matrix multiplier :math:`equation not available` used to form the + viscous damping matrix :math:`equation not available`, where :math:`equation not available` is + the mass matrix. + + Values of :math:`equation not available` can also be input as a material property ( :ref:`mp`,ALPD + or :ref:`tb`,SDAMP,,,,ALPD). If ALPD in either form is included, the ALPD value is added to the + :ref:`alphad` value as appropriate. (See `Material Damping + `_ `Damping + Matrices `_ + :ref:`antype`,STATIC) or buckling ( :ref:`antype`,BUCKLE) analyses. This command is also valid in PREP7. """ command = f"ALPHAD,{value}" return self.run(command, **kwargs) - def betad(self, value="", **kwargs): - """Defines the stiffness matrix multiplier for damping. + def betad(self, value: str = "", **kwargs): + r"""Defines the stiffness matrix multiplier for damping. - APDL Command: BETAD + Mechanical APDL Command: `BETAD `_ Parameters ---------- - value + value : str Stiffness matrix multiplier for damping. Notes ----- - This command defines the stiffness matrix multiplier β used to form the - viscous damping matrix [C] = β [K] where [K] is the stiffness matrix. - Values of : β may also be input as a material property (use the BETD - label on the MP command). If BETD is included, the BETD value is added - to the BETAD value as appropriate (see Damping Matrices in the - Mechanical APDL Theory Reference). Damping is not used in the static - (ANTYPE,STATIC) or buckling (ANTYPE,BUCKLE) analyses. + .. _BETAD_notes: + + This command defines the stiffness matrix multiplier :math:`equation not available` used to form + the viscous damping matrix :math:`equation not available`, where :math:`equation not available` + is the stiffness matrix. + + Values of :math:`equation not available` can also be input as a material property ( :ref:`mp`,BETD + or :ref:`tb`,SDAMP,,,,BETD). If BETD in either form is included, the BETD value is added to the + :ref:`betad` value as appropriate. (See `Material Damping + `_ `Damping + Matrices `_ + :ref:`antype`,STATIC) or buckling ( :ref:`antype`,BUCKLE) analyses. This command is also valid in PREP7. """ command = f"BETAD,{value}" return self.run(command, **kwargs) - def dmprat(self, ratio="", **kwargs): - """Sets a constant modal damping ratio. + def dampopt(self, option: str = "", value: str = "", **kwargs): + r"""Sets damped eigensolver options. + + Mechanical APDL Command: `DAMPOPT `_ + + **Command default:** + + .. _DAMPOPT_default: + + By default, the shift strategy is not activated for the damped eigensolver. This ensures a faster + solve process but limits the number of eigenvalues that can be found. + + The default memory allocation strategy is used. Mechanical APDL evaluates the resources of the machine to + choose the in-core or out-of-core mode. + + Parameters + ---------- + option : str + Damped eigensolver option: + + * ``SHIFT`` - Activate or deactivate the shift strategy of the damped eigensolver to move to a frequency range of + interest. The ``FREQB`` value of the :ref:`modopt` command is used to choose the first frequency + shift (see notes for details). + + Valid input for ``Value`` when ``Option`` = SHIFT: + + * ``OFF`` - Do not activate the shift strategy. + + * ``ON`` - Activate the shift strategy (default). + + * ``MEMORY`` - Controls the memory allocation strategy for the Damped eigensolver. + + Valid input for ``Value`` when ``Option`` = MEMORY: + + * ``DEFAULT`` - Default memory configuration (default). Everything is determined dynamically with + respect to current machine resources. + + * ``INCORE`` - Fully in-core memory configuration. + + * ``MIX1`` - First level of mixed in-core / out-of-core configuration. + + * ``MIX2`` - Second level of mixed in-core / out-of-core configuration. + + * ``OUTOFCORE`` - Fully out-of-core memory configuration. + + value : str + Assigned value for the specified ``Option`` (as described above). + + Notes + ----- + + .. _DAMPOPT_notes: + + :ref:`dampopt` specifies options to be used with the damped eigensolver ( :ref:`modopt`,DAMP) + during a modal analysis ( :ref:`antype`,MODAL). + + Activating the shift strategy ( ``Option`` = SHIFT and ``Value`` = ON) enables the eigensolver to + find higher frequency eigenvalues that might otherwise be missed. The SHIFT option has two + objectives: + + * Extract high frequency eigenvalues according to the ``FREQB`` argument specified with + :ref:`modopt`. + + * Unlock an auto-shift feature, so the algorithm will chain several analyses automatically then + aggregate the solutions in one single results set. + + If ``FREQE`` is specified on :ref:`modopt`, the specified value is used to filter the complex + eigenfrequencies based on magnitude. + + When the shift strategy is activated ( :ref:`dampopt`,SHIFT,ON) + + * and ``FREQB`` on :ref:`modopt` is specified, the damped eigensolver only produces eigenfrequencies + with a real part greater than ``FREQB`` + + * and ``FREQB`` on :ref:`modopt` is not specified, the damped eigensolver finds eigenvalues closest + to the 0 Hz point. + + **Memory Allocation Option (** ``Option`` = MEMORY) + + The damped eigensolver algorithm allocates two main pools of memory: + + Memory for the internal damped eigensolver iterations. + + Memory for the specific damped eigensolver working arrays. + + The following table shows how memory is allocated for each option. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + The MIX1 configuration typically uses more memory than the MIX2 configuration, except when a large + number of modes are requested for a small model. + + **Example Usage** + + .. _DAMPOPT_example: + + `Example: Shift Option Usage on DAMPOPT + `_ + """ + command = f"DAMPOPT,{option},{value}" + return self.run(command, **kwargs) + + def dmprat(self, ratio: str = "", **kwargs): + r"""Sets a modal damping ratio. - APDL Command: DMPRAT + Mechanical APDL Command: `DMPRAT `_ + + **Command default:** + + .. _DMPRAT_default: + + Use damping as defined by `Damping + `_ Parameters ---------- - ratio + ratio : str Modal damping ratio (for example, 2% is input as 0.02). Notes ----- - Sets a constant damping ratio for use in the mode-superposition - transient (ANTYPE,TRANS) or harmonic (ANTYPE,HARMIC) analysis and the - spectrum (ANTYPE,SPECTR) analysis. + + .. _DMPRAT_notes: + + Sets a damping ratio for use in a mode-superposition transient analysis ( :ref:`antype`,TRANS with + :ref:`trnopt`,MSUP), a mode-superposition harmonic analysis ( :ref:`antype`,HARMIC with + :ref:`hropt`,MSUP) analysis, or a spectrum ( :ref:`antype`,SPECTR) analysis. + + :ref:`dmprat` can also be defined in a substructure analysis that uses component mode synthesis. The + damping ratio is added on the diagonal of the reduced damping matrix, as explained in `Component + Mode Synthesis (CMS) + `_ This command is also valid in PREP7. + + **Additional Information** + + .. _DMPRAT_addlinfo: + + `Damping Matrices + `_ """ command = f"DMPRAT,{ratio}" return self.run(command, **kwargs) - def dmpstr(self, coeff="", **kwargs): - """Sets a constant structural damping coefficient. + def dmpstr(self, coeff: str = "", dmpsfreqtab: str = "", **kwargs): + r"""Sets constant structural damping data. + + Mechanical APDL Command: `DMPSTR `_ - APDL Command: DMPSTR + **Command default:** + + .. _DMPSTR_default: + + Use damping as defined by `Damping + `_ Parameters ---------- - coeff - Structural damping coefficient. + coeff : str + Constant structural damping coefficient. + + dmpsfreqtab : str + Average excitation frequency table (Hz) for the calculation of equivalent viscous damping from + structural damping input ( :ref:`dmpstr` and :ref:`mp`,DMPS) in a full transient analysis. + Enclose the table name in percent signs (%) and use the :ref:`dim` command to define the table + with primary variable TIME. To define a constant frequency instead of a table, see + :ref:`trnopt`. Notes ----- - Sets a constant structural (or hysteretic) damping coefficient for use - in harmonic (ANTYPE,HARMIC) analyses (FULL, MSUP, and VT) and modal - analyses (ANTYPE,MODAL with MODOPT,UNSYM, DAMP or QRDAMP). - Note that for structures with multiple materials, MP,DMPR can also be - used to specify constant structural material damping on a per material - basis. Note that if both DMPSTR and MP,DMPR are specified, the damping - effects are additive. + .. _DMPSTR_notes: + + Sets a constant structural (or hysteretic) damping coefficient for use in these analysis types: + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `Krylov + `_, + or mode-superposition [ :ref:`DMPSTR_mode-sup_LoadSupport` ] - Caution:: : DMPSTR adds the damping contribution as gK, whereas MP,DMPR - adds the contribution on a per-material basis as 2gK. For more - information, see Damping Matrices in the Mechanical APDL Theory - Reference. + * Modal ( :ref:`antype`,MODAL) with :ref:`modopt`,UNSYM, DAMP, or QRDAMP. + + .. _DMPSTR_mode-sup_LoadSupport: + + In a mode-superposition harmonic or transient analysis, you must apply the load in the modal portion + of the analysis. Mechanical APDL calculates a load vector and writes it to the :file:`MODE` file, + which you + can apply via the :ref:`lvscale` command. + + :ref:`dmpstr` is also supported in transient ( :ref:`antype`,TRANS) analyses (full or QRDAMP mode- + superposition) as an equivalent viscous damping when an average excitation frequency is specified. + For a full or mode-superposition transient, specify a constant excitation frequency as ``DMPSFreq`` + on the :ref:`trnopt` command. For a full transient, you can alternatively specify a table of + frequencies using ``DMPSFreqTab`` on this command. ``DMPSFreqTab`` overwrites ``DMPSFreq`` on + :ref:`trnopt`. + + Note that for structures with multiple materials, :ref:`mp`,DMPS can also be used to specify + constant structural material damping on a per material basis. If both :ref:`dmpstr` and + :ref:`mp`,DMPS are specified, the damping effects are additive. This command is also valid in PREP7. """ - command = f"DMPSTR,{coeff}" + command = f"DMPSTR,{coeff},{dmpsfreqtab}" return self.run(command, **kwargs) - def frqscl(self, scaling="", **kwargs): - """Turns on automatic scaling of the entire mass matrix and frequency + def frqscl(self, scaling: str = "", **kwargs): + r"""Turns on automatic scaling of the entire mass matrix and frequency range for modal analyses. + + Mechanical APDL Command: `FRQSCL `_ - APDL Command: FRQSCL - range for modal analyses using the Block Lanczos, PCG Lanczos, or - Supernode mode extraction method. + **Command default:** + Mechanical APDL uses automatic scaling if appropriate. Parameters ---------- - scaling + scaling : str - Off - Do not use automatic scaling of the mass matrix and frequency range. + * ``Off`` - Do not use automatic scaling of the mass matrix and frequency range. - On - Use automatic scaling of the mass matrix and frequency range. + * ``On`` - Use automatic scaling of the mass matrix and frequency range. Notes ----- - Use this command to deactivate or force activation of automatic scaling - of the entire mass matrix and frequency range for modal analyses where - the entire mass matrix is significantly different (i.e., orders of - magnitude difference) than the entire stiffness matrix (for example, - due to the particular unit system being used). Where the mass matrix - is significantly smaller compared to the stiffness matrix, the - eigenvalues will tend to approach very large numbers (>10e12), making - the Block Lanczos, PCG Lanczos, or Supernode mode extraction method - less efficient and more likely to miss modes. - - ANSYS uses scaling (if appropriate) by default. However, you can issue - FRQSCL,ON to force the entire mass matrix and frequency range to be - scaled to bring the stiffness and mass matrices closer together in - terms of orders of magnitude, improving efficiency and reducing the - likelihood of missed modes. The resulting eigenvalues are then - automatically scaled back to the original system. If you are using - micro MKS units, where the density is typically very small compared to - the stiffness, you may want to issue FRQSCL,ON to force scaling on. - - If the stiffness and mass are on the same scale, FRQSCL,ON has no - effect. - - This command is available only for modal analyses using the Block - Lanczos, PCG Lanczos, or Supernode mode extraction method (MODOPT,LANB, - LANPCG, or SNODE). - - This command is not valid and has no effect when used in conjunction - with the MSAVE,ON command in a modal analysis with the PCG Lanczos mode - extraction method. + This command is available only for modal analyses using the Block Lanczos, PCG Lanczos, Supernode, + Subspace, or Unsymmetric mode extraction method ( :ref:`modopt`,LANB, LANPCG, SNODE, SUBPS, or + UNSYM). + + Use this command to deactivate or force activation of automatic scaling of the entire mass matrix + and frequency range for modal analyses where the entire mass matrix is significantly different (that + is, orders of magnitude different) than the entire stiffness matrix (for example, due to the + particular unit system being used). Where the mass matrix is significantly smaller compared to the + stiffness matrix, the eigenvalues will tend to approach very large numbers (>10e12), making the + selected mode-extraction method less efficient and more likely to miss modes. + + You can force the entire mass matrix and frequency range to be scaled via :ref:`frqscl`,ON. Doing so + brings the stiffness and mass matrices closer together in terms of orders of magnitude, improving + efficiency and reducing the likelihood of missed modes. The resulting eigenvalues are then + automatically scaled back to the original system. If you are using micro MKS units, where the + density is typically very small compared to the stiffness, you may want to force scaling on. + + If the stiffness and mass are on the same scale, :ref:`frqscl`,ON has no effect. + + This command is not valid and has no effect when used with :ref:`msave`,ON in a modal analysis with + the PCG Lanczos mode extraction method. """ command = f"FRQSCL,{scaling}" return self.run(command, **kwargs) - def harfrq(self, freqb="", freqe="", logopt="", freqarr="", toler="", **kwargs): - """Defines the frequency range in a harmonic analysis. + def harfrq( + self, + freqb: str = "", + freqe: str = "", + logopt: str = "", + freqarr: str = "", + toler: str = "", + **kwargs, + ): + r"""Defines the frequency range in a harmonic analysis. - APDL Command: HARFRQ + Mechanical APDL Command: `HARFRQ `_ Parameters ---------- - freqb - Frequency (Hz) at the beginning of the FREQB to FREQE range (if - FREQE > FREQB). If FREQE is blank, the solution is done only at - frequency FREQB (the central frequency of octave bands, when LogOpt - = OB1, OB2, OB3, OB6, OB12 or OB24). - - freqe - Frequency at end of this range. Solutions are done at an interval - of (FREQE-FREQB) / NSBSTP, ending at FREQE. No solution is done at - the beginning of the frequency range. NSBSTP is input via the - NSUBST command. See the EXPSOL command documentation for expansion - pass solutions. - - -- - Reserved. - - logopt - Logarithm frequency span. Solutions are done at an interval of - (log(FREQE) - log(FREQB)) / (NSBSTP-1), (NSBSTP>1). The central - frequency or beginning frequency is used for NSBSTP = 1. Valid - values are: - - OB1 - Octave band. - - OB2 - 1/2 octave band. - - OB3 - 1/3 octave band. - - OB6 - 1/6 octave band. - - OB12 - 1/12 octave band. - - OB24 - 1/24 octave band. - - LOG - General logarithm frequency span. - - freqarr - An array containing frequency values (Hz). Combined with the - tolerance argument, Toler, these values are merged with values - calculated based on the specifications from FREQB, FREQE, and - LogOpt, as well NSBSTP on the NSUBST command and Clust on the HROUT - command. Enclose the array name in percent (%) signs (for example, - HARFRQ,,,,,%arrname%). Use ``*DIM`` to define the array. - - toler - Tolerance to determine if a user input frequency value in FREQARR - is a duplicate and can be ignored. Two frequency values are - considered duplicates if their difference is less than the - frequency range multiplied by the tolerance. The default value is 1 - x 10-5. + freqb : str + Frequency (Hz) at the beginning of the ``FREQB`` to ``FREQE`` range (if ``FREQE`` > ``FREQB`` ). + If ``FREQE`` is blank, the solution is done only at frequency ``FREQB`` (the central frequency + of octave bands, when ``LogOpt`` = OB1, OB2, OB3, OB6, OB12 or OB24). + + freqe : str + Frequency at end of this range. For non-logarithm spacing ( ``LogOpt`` is blank), solutions are + done at an interval of ( ``FREQE`` - ``FREQB`` ) / ``NSBSTP``, ending at ``FREQE``, and no + solution is done at the beginning of the frequency range, ``FREQB``. ``NSBSTP`` is input via the + :ref:`nsubst` command. See the :ref:`expsol` command documentation for expansion pass solutions. + + logopt : str + Logarithm frequency span. Solutions are done at an interval of (log( ``FREQE`` ) - log( ``FREQB`` )) + / ( ``NSBSTP`` -1), ( ``NSBSTP`` >1). The central frequency or beginning frequency is used for + ``NSBSTP`` = 1. Valid values are: + + * ``OB1`` - Octave band. + + * ``OB2`` - 1/2 octave band. + + * ``OB3`` - 1/3 octave band. + + * ``OB6`` - 1/6 octave band. + + * ``OB12`` - 1/12 octave band. + + * ``OB24`` - 1/24 octave band. + + * ``LOG`` - General logarithm frequency span. + + freqarr : str + An array containing frequency values (Hz). Combined with the tolerance argument, ``Toler``, + these values are merged with values calculated based on the specifications from ``FREQB``, + ``FREQE``, and ``LogOpt``, as well ``NSBSTP`` on the :ref:`nsubst` command and ``Clust`` on the + :ref:`hrout` command. Enclose the array name in percent (%) signs (for example, + :ref:`harfrq`,,,,,%arrname%). Use :ref:`dim` to define the array. + + toler : str + Tolerance to determine if a user input frequency value in ``FREQARR`` is a duplicate and can be + ignored. Two frequency values are considered duplicates if their difference is less than the + frequency range multiplied by the tolerance. The default value is 1 x 10 :sup:`-5`. Notes ----- - Defines the frequency range for loads in the harmonic analysis - (ANTYPE,HARMIC). - Do not use this command for a harmonic ocean wave analysis (HROCEAN). + .. _HARFRQ_notes: - When frequencies are user-defined, the array FREQARR must be one- - dimensional and contain positive values. User-defined frequency input - is not supported in the following cases: + Defines the frequency range for loads in the harmonic analysis ( :ref:`antype`,HARMIC). - in a cyclic symmetry harmonic analysis + Do not use this command for a `harmonic ocean wave analysis + `_ + ( :ref:`hrocean` ). - when the Variational Technology method is used (Method = VT on the - HROPT command) + When frequencies are user-defined, the array ``FREQARR`` must be one-dimensional and contain + positive values. User-defined frequency input is not supported when the `frequency-sweep + `_ method is + used ( :ref:`hropt`,VT ). This command is also valid in PREP7. """ command = f"HARFRQ,{freqb},{freqe},,{logopt},{freqarr},{toler}" return self.run(command, **kwargs) - def hrexp(self, angle="", **kwargs): - """Specifies the phase angle for the harmonic analysis expansion pass. + def hrexp(self, angle: str = "", **kwargs): + r"""Specifies the phase angle for the harmonic analysis expansion pass. - APDL Command: HREXP + Mechanical APDL Command: `HREXP `_ Parameters ---------- - angle - Phase angle (degrees) for expansion pass. If ALL (default), use - both 0.0° (real) and 90.0° (imaginary) phase angles. + angle : str + Phase angle (degrees) for expansion pass. If ALL (default), use both 0.0° (real) and 90.0° + (imaginary) phase angles. Notes ----- - Specifies the phase angle where the expansion pass will be done for a - harmonic mode-superposition expansion pass. - For a specific angle, the following real solution is stored in the - results (``*.rst``) file: + .. _HREXP_notes: + + Specifies the phase angle where the expansion pass will be done for a harmonic mode-superposition + expansion pass. + + For a specific angle, the following real solution is stored in the results (\2.rst) file: + + .. math:: + + equation not available + + Where: + + i is the degree of freedom number. - If ANGLE is ALL, both the real and imaginary parts of the solution are - stored in the results file. + :math:`equation not available` is the amplitude of thei th degree of freedom solution - For more details about the solution equations, see Harmonic Analyses in - the Mechanical APDL Theory Reference. + Φ :sup:`i` is the phase shift angle of the i th degree of freedom solution - This command is ignored if the HROPT command has been issued with - Method = VT or Method = VTRU. + ϕ is the supplied phase shift angle ( ``ANGLE`` ) + + If ``ANGLE`` is ALL, both the real and imaginary parts of the solution are stored in the results + file. + + For more details about the solution equations, see `Harmonic Analyses + `_ + in the `Mechanical APDL Theory Reference + `_. + + This command is ignored if the :ref:`hropt` command has been issued with ``Method`` = KRYLOV, VT, or + VTPA. This command is also valid in PREP7. """ command = f"HREXP,{angle}" return self.run(command, **kwargs) - def hrocean(self, type_="", nphase="", **kwargs): - """Perform the harmonic ocean wave procedure (HOWP). + def hrocean(self, type_: str = "", nphase: str = "", **kwargs): + r"""Perform the harmonic ocean wave procedure (HOWP). - APDL Command: HROCEAN + Mechanical APDL Command: `HROCEAN `_ Parameters ---------- - type\\_ - Specifies how to include ocean wave information in a harmonic - analysis: - - HARMONIC - Performs a harmonic analysis using both real and imaginary load vectors - calculated via the harmonic ocean wave procedure (HOWP). - This behavior is the default. This option performs a - harmonic analysis running at a frequency determined by - the wave period (specified via OCTABLE command input). - - STATIC - Performs a static analysis using both real and imaginary load vectors - (calculated via HOWP). This option works by performing a - harmonic analysis running at a frequency of 0.0. - - OFF - Deactivates a previously activated HOWP and performs a standard harmonic - analysis. - - nphase - Positive number specifying the number of phases to calculate - forces. This value must be at least 8. The default value is 20. + type_ : str + Specifies how to include ocean wave information in a harmonic analysis: + + * ``HARMONIC`` - Performs a harmonic analysis using both real and imaginary load vectors calculated + via the `harmonic ocean wave procedure (HOWP) + `_. + This behavior is the default. This option performs a harmonic analysis running at a frequency + determined by the wave period (specified via :ref:`octable` command input). + + * ``STATIC`` - Performs a static analysis using both real and imaginary load vectors (calculated via + HOWP). This option works by performing a harmonic analysis running at a frequency of 0.0. + + * ``OFF`` - Deactivates a previously activated HOWP and performs a standard harmonic analysis. + + nphase : str + Positive number specifying the number of phases to calculate forces. This value must be at least + 8. The default value is 20. Notes ----- - The HROCEAN command applies ocean wave information (obtained via the - OCDATA and OCTABLE commands) in a harmonic analysis (ANTYPE,HARMIC) as - real and imaginary forces. + + .. _HROCEAN_notes: + + The :ref:`hrocean` command applies ocean wave information (obtained via the :ref:`ocdata` and + :ref:`octable` commands) in a harmonic analysis ( :ref:`antype`,HARMIC) as real and imaginary + forces. You can apply only one ocean load at a time. - The applied frequency in the harmonic (Type = HARMONIC) analysis is - based on the wave period input on the OCTABLE command (and not on - HARFRQ command input, which cannot be used). Phase-shift input on the - OCTABLE command is ignored. + The applied frequency in the harmonic ( ``Type`` = HARMONIC) analysis is based on the wave period + input on the :ref:`octable` command (and not on :ref:`harfrq` command input, which cannot be used). + Phase-shift input on the :ref:`octable` command is ignored. - HOWP does not generate a damping matrix. If you require a damping - matrix, you must add it separately. + HOWP does not generate a damping matrix. If you require a damping matrix, you must add it + separately. - The command applies to regular wave types only (Airy with one wave - component, Wheeler with one wave component, Stokes, and stream - function). Irregular wave types are not supported. For information - about wave types, see Hydrodynamic Loads in the Mechanical APDL Theory - Reference. + The command applies to regular wave types only (Airy with one wave component, Wheeler with one wave + component, Stokes, and stream function). Irregular wave types are not supported. For information + about wave types, see `Hydrodynamic Loads + `_ - The program calculates the forces on each load component of each - element at NPHASE solutions, spread evenly over one wave cycle. Then, - the minimum and maximum, and the phase between them, are calculated. - The command uses the resulting information to generate the real and - imaginary loads. + The program calculates the forces on each load component of each element at ``NPHASE`` solutions, + spread evenly over one wave cycle. Then, the minimum and maximum, and the phase between them, are + calculated. The command uses the resulting information to generate the real and imaginary loads. HOWP cannot be used with stress stiffening. - HOWP works with the full harmonic analysis method (HROPT,FULL) only. + HOWP works with the full harmonic analysis method ( :ref:`hropt`,FULL) only. - For more information, see Harmonic Ocean Wave Procedure (HOWP) in the - Mechanical APDL Theory Reference. + For more information, see `Harmonic Ocean Wave Procedure (HOWP) + `_ This command is also valid in PREP7. """ command = f"HROCEAN,{type_},{nphase}" return self.run(command, **kwargs) - def hropt(self, method="", maxmode="", minmode="", mcout="", damp="", **kwargs): - """Specifies harmonic analysis options. + def hropt( + self, + method: str = "", + value1: str = "", + value2: str = "", + value3: str = "", + value4: str = "", + value5: str = "", + **kwargs, + ): + r"""Specifies harmonic analysis options. - APDL Command: HROPT + Mechanical APDL Command: `HROPT `_ Parameters ---------- - method + method : str Solution method for the harmonic analysis: - AUTO - Automatically select the most efficient method. Either the FULL method or the - Variational Technology method is selected depending on the - model. (default method). - - FULL - Full method. + * ``AUTO`` - Automatically select the most efficient method (default). Either the full method (FULL) + or the frequency-sweep method (VT) is selected, depending on the model. For ``Method`` = AUTO, + ``Value1``.. ``Value5`` are unused fields. - MSUP - Mode-superposition method. + * ``FULL`` - Full method. For ``Method`` = AUTO, ``Value1``.. ``Value5`` are unused fields. - VT - Variational Technology method (based on FULL harmonic algorithm). + * ``MSUP`` - Mode-superposition method. See :ref:`HROPT_MSUP`. - VTPA - Variational Technology perfect absorber method (based on FULL harmonic - algorithm). + * ``VT`` - Frequency-sweep (Variational Technology) method (based on the FULL harmonic algorithm). See + :ref:`HROPT_VT_VTPA`. - VTRU - Variational Technology reuse method (based on FULL harmonic algorithm). + * ``VTPA`` - Frequency-sweep (Variational Technology) perfect absorber method (based on the FULL harmonic + algorithm). See :ref:`HROPT_VT_VTPA`. - maxmode - Largest mode number to be used to calculate the response (for - Method = MSUP only). Defaults to the highest mode calculated in - the preceding modal analysis. + * ``KRYLOV`` - Frequency-sweep Krylov method. See :ref:`HROPT_KRYLOV`. - minmode - Smallest mode number to be used (for Method = MSUP only). Defaults - to 1. + The Krylov approximation can be run using macros as customizable templates as described in. + Alternatively, you can perform a Krylov solution without customization as described in `Krylov + Method Implemented using Mechanical APDL Commands + `_ - mcout - Modal coordinates output key (valid only for the mode superposition - method MSUP): + If the solution method is not specified, the program automatically selects either the Full method or + the frequency-sweep method, depending on which method is most efficient for the model. The + frequency-sweep method uses the underlying Variational Technology method. - NO - No output of modal coordinates (default). + value1 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - YES - Output modal coordinates to the text file jobname.MCF. + value2 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - damp - Damping mode for frequency-dependent material properties (valid - only for the Variational Technology Method VT). + value3 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - Hysteretic - Not proportional to the frequency. + value4 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. - Viscous - Proportional to the frequency (default). + value5 : str + The description of the argument is missing in the Python function. Please, refer to the `command + documentation + `_ for further + information. Notes ----- - Specifies the method of solution for a harmonic analysis - (ANTYPE,HARMIC). If used in SOLUTION, this command is valid only - within the first load step. See the product restrictions indicated - below. - For cyclic symmetry mode-superposition harmonic solutions, MAXMODE and - MINMODE are ignored. + .. warning:: + + This function contains specificities regarding the argument definitions. + Please refer to the `command documentation `_ + for further explanations. + + .. _HROPT_notes: - To include residual vectors in your mode-superposition harmonic - analysis, specify RESVEC,ON. + Specifies the method of solution for a harmonic analysis ( :ref:`antype`,HARMIC). + + If used in SOLUTION, this command is valid only within the first load step. This command is also valid in PREP7. - Distributed ANSYS Restriction: The VTRU method is not supported. + **For** ``Method`` = MSUP: + + * For cyclic symmetry mode-superposition harmonic solutions, ``MAXMODE`` and ``MINMODE`` are + ignored. + + * To include `residual vectors + `_ + in your `mode-superposition harmonic analysis + `_, + specify :ref:`resvec`,ON. + * ``MAXMODE`` and ``MINMODE`` are ignored after a modal restart analysis where remote modal files + usage ( :ref:`moddir` ) and residual vector calculation ( :ref:`resvec`,ON) have been activated. """ - command = f"HROPT,{method},{maxmode},{minmode},{mcout},{damp}" + command = f"HROPT,{method},{value1},{value2},{value3},{value4},{value5}" return self.run(command, **kwargs) - def hrout(self, reimky="", clust="", mcont="", **kwargs): - """Specifies the harmonic analysis output options. + def hrout( + self, + reimky: str = "", + clust: str = "", + mcont: str = "", + engcalc: str = "", + **kwargs, + ): + r"""Specifies the harmonic analysis output options. - APDL Command: HROUT + Mechanical APDL Command: `HROUT `_ Parameters ---------- - reimky + reimky : str Real/Imaginary print key: - ON - Print complex displacements as real and imaginary components (default). + * ``ON`` - Print complex displacements as real and imaginary components (default). + + * ``OFF`` - Print complex displacements as amplitude and phase angle (degrees). + + clust : str + Cluster option (for :ref:`hropt`,MSUP): - OFF - Print complex displacements as amplitude and phase angle (degrees). + * ``OFF`` - Uniform spacing of frequency solutions (default). - clust - Cluster option (for HROPT,MSUP): + * ``ON`` - Cluster frequency solutions about natural frequencies. - OFF - Uniform spacing of frequency solutions (default). + mcont : str + Mode contributions key (for :ref:`hropt`,MSUP): - ON - Cluster frequency solutions about natural frequencies. + * ``OFF`` - No print of mode contributions at each frequency (default). - mcont - Mode contributions key (for HROPT,MSUP): + * ``ON`` - Print mode contributions at each frequency. + + engcalc : str + Additional element energies calculation key: - OFF - No print of mode contributions at each frequency (default). + * ``NO`` - Do not calculate additional energies (default). - ON - Print mode contributions at each frequency. + * ``YES`` - Calculate average, amplitude, and peak values for the following: stiffness and kinetic + energies, damping energy, and work done by external loads. Notes ----- - Specifies the harmonic analysis (ANTYPE,HARMIC) output options. If - used in SOLUTION, this command is valid only within the first load - step. OUTPR,NSOL must be specified to print mode contributions at each - frequency. - This command is ignored if the HROPT command has been issued with - Method = VT, VTPA, or VTRU. Displacements are not available at expanded - frequencies with these solution methods. + .. _HROUT_notes: - For cyclic symmetry mode-superposition harmonic solutions, the cluster - option is not available. + Specifies the harmonic analysis ( :ref:`antype`,HARMIC) output options. If used in SOLUTION, this + command is valid only within the first load step. :ref:`outpr`,NSOL must be specified to print mode + contributions at each frequency. + + If the calculation of additional energies is requested ( ``EngCalc`` = YES) in a mode-superposition + harmonic analysis ( ``Method`` = MSUP on the :ref:`hropt` command), work done by external loads is + not calculated if ``MSUPkey`` = YES on the :ref:`mxpand` command. If ``MSUPkey`` = NO, work due to + element loads is calculated, but not work due to nodal loads. + + Only the ``Reimky`` argument is supported and applicable for frequency-sweep harmonic analyses using + the `Krylov + `_ + or `Variational Technology + `_ Methods. All + other arguments are ignored if the :ref:`hropt` command has been issued with ``Method`` = KRYLOV, + VT, or VTPA. This command is also valid in PREP7. """ - command = f"HROUT,{reimky},{clust},{mcont}" + command = f"HROUT,{reimky},{clust},{mcont},{engcalc}" return self.run(command, **kwargs) - def lvscale(self, fact="", ldstep="", **kwargs): - """Scales the load vector for mode-superposition analyses. + def kryopt(self, maxdim: str = "", restol: str = "", **kwargs): + r"""Specifies solution options for a Krylov method harmonic analysis. - APDL Command: LVSCALE + Mechanical APDL Command: `KRYOPT `_ Parameters ---------- - fact - Scale factor applied to both the real and imaginary (if they exist) - components of the load vector. Defaults to 0.0. + maxdim : str + Maximum dimension of subspace. The default size is automatically determined by the program + (ranges around 50). - ldstep - Specifies the load step number from the modal analysis - (MODCONT,ON). It corresponds to the load vector number. Defaults to - 1. The maximum value is 240. + restol : str + Tolerance used to verify the L-2 norm values of calculated residuals and issue a warning if + ``RESTOL`` is exceeded throughout the entire frequency range. Default = 0.05. Notes ----- - Specifies the scale factor for the load vector that was created in a - modal (ANTYPE,MODAL) analysis. Applies only to the mode-superposition - transient analysis (ANTYPE,TRANS), mode-superposition harmonic analysis - (ANTYPE,HARMIC), random vibration analysis (ANTYPE,SPECTR with - SPOPT,PSD), and multiple point response spectrum analysis - (ANTYPE,SPECTR with SPOPT,MPRS). For PSD and MPRS analyses, LVSCALE is - only applicable for pressure loading. - - The LVSCALE command supports tabular boundary conditions (%TABNAME_X%) - for FACT input values only as a function of time in the mode- - superposition transient (ANTYPE,TRANS) or as a function of frequency in - mode-superposition harmonic (ANTYPE,HARMIC). - - MPC contact generates constraint equations that can include constant - terms (included on the right-hand side of the system equation). The - LVSCALE command scales the constant terms. - - In mode-superposition transient and harmonic analyses, all of the load - vectors need to be scaled in the first load step. Use a zero scale - factor if they are not actually used in this first load step. : - Similarly, in random vibration and multipoint response spectrum - analyses, all of the load vectors need to be scaled in the first - participation factor calculation (PFACT). : Use a zero scale factor if - they are not actually used for the first input table. + + .. _KRYOPT_notes: + + This command is used to specify solution options for a harmonic analysis solved with the Krylov + method ( ``Method`` = KRYLOV on :ref:`hropt`, see also `Frequency-Sweep Harmonic Analysis via the + Krylov Method + `_ + + Increasing subspace size ( ``MAXDIM`` ) improves solution accuracy with the trade-off of increased + computational cost and additional memory requirements. + """ + command = f"KRYOPT,{maxdim},,,{restol}" + return self.run(command, **kwargs) + + def lvscale(self, fact: str = "", ldstep: str = "", **kwargs): + r"""Scales the load vector for mode-superposition analyses. + + Mechanical APDL Command: `LVSCALE `_ + + Parameters + ---------- + fact : str + Scale factor applied to both the real and imaginary (if they exist) components of the load + vector. Defaults to 0.0. + + ldstep : str + Specifies the load step number from the modal analysis ( :ref:`modcont`,ON). It corresponds to + the load vector number. Defaults to 1. The maximum admissible value is the number of vectors + written in the :file:`Jobname.MODE` file. + + Notes + ----- + + .. _LVSCALE_notes: + + Specifies the scale factor for the load vector that was created in a modal ( :ref:`antype`,MODAL) + analysis. Applies only to the mode-superposition transient analysis ( :ref:`antype`,TRANS), mode- + superposition harmonic analysis ( :ref:`antype`,HARMIC), random vibration analysis ( :ref:`antype` + ,SPECTR with :ref:`spopt`,PSD), and multiple point response spectrum analysis ( :ref:`antype` + ,SPECTR with :ref:`spopt`,MPRS). For PSD and MPRS analyses, :ref:`lvscale` is only applicable for + pressure loading. + + The :ref:`lvscale` command supports tabular boundary conditions (%TABNAME_X%) for ``FACT`` input + values only as a function of time in the mode-superposition transient ( :ref:`antype`,TRANS) or as + a function of frequency in mode-superposition harmonic ( :ref:`antype`,HARMIC). + + `MPC contact + `_ generates + constraint equations that can include constant terms (included on the right-hand side of the system + equation). The :ref:`lvscale` command scales the constant terms. + + In mode-superposition transient and harmonic analyses, all of the load vectors need to be scaled in + the first load step. Use a zero scale factor if they are not actually used in this first load step. + Similarly, in random vibration and multipoint response spectrum analyses, all of the load vectors + need to be scaled in the first participation factor calculation ( :ref:`pfact` ). Use a zero scale + factor if they are not actually used for the first input table. This command is also valid in PREP7. """ command = f"LVSCALE,{fact},{ldstep}" return self.run(command, **kwargs) - def mascale(self, massfact="", **kwargs): - """Activates scaling of the entire system matrix. + def mascale(self, massfact: str = "", **kwargs): + r"""Activates scaling of the entire system matrix. - APDL Command: MASCALE + Mechanical APDL Command: `MASCALE `_ Parameters ---------- - massfact - Scaling factor (> 0) for the mass matrix. Default = 1.0. + massfact : str + Scaling factor (> 0) for the mass matrix. Default = 1.0. Notes ----- + + .. _MASCALE_notes: + This command is supported in the first load step of the analysis only. + The following features are not affected by the scaling: - * Ocean loading - * Steady-state rolling SSTATE + * Ocean loading ( `Applying Ocean Loading from a Hydrodynamic Analysis + `_ + + * Steady-state rolling ( :ref:`sstate` ) + + The mass-related information (mass, center of mass, and mass moments of inertia) printed in the mass + summary is based on unscaled mass properties. + """ + command = f"MASCALE,{massfact}" + return self.run(command, **kwargs) + + def mcfopt( + self, + format_: int | str = "", + type_: int | str = "", + norm: int | str = "", + **kwargs, + ): + r"""Specifies options for the Modal Coordinates File ( :file:`Jobname.mcf` ). + + Mechanical APDL Command: `MCFOPT `_ + + Parameters + ---------- + format_ : int or str + :file:`Jobname.mcf` file format: + + * ``0`` - ASCII with wrap for more than 25 values (harmonic analysis) or 50 values (transient + analysis) (default). + + * ``1`` - ASCII. + + type_ : int or str + Output form of the complex modal coordinates - Only supported for ``Format`` = 1: + + * ``0`` - Real and imaginary parts (default). + + * ``1`` - Amplitude and phase angle in degree. + + norm : int or str + Mode shape normalization for the calculation of the modal coordinates - Only supported for ``Format`` = 1: + + * ``0`` - The modes are mass normalized (default). + + * ``1`` - The modes are normalized to unity. - The mass-related information (mass, center of mass, and mass - moments of inertia) printed in the mass summary is based on - unscaled mass properties. + Notes + ----- + + .. _MCFOPT_notes: + + Options specified with :ref:`mcfopt` are processed when a request is made to write the + ``Jobname.mcf`` file by issuing :ref:`trnopt` or :ref:`hropt` with ``MCFwrite`` = ON. + + If you specify normalized to unity for the modal coordinates ( ``Norm`` = 1), the generalized mass + must be available (see ). Note that this option is independent from the normalization of the modes + specified during the modal analysis ( ``NrmKey`` on :ref:`modopt` command). """ - return self.run(f"MASCALE,{massfact}", **kwargs) + command = f"MCFOPT,{format_},{type_},{norm}" + return self.run(command, **kwargs) - def mdamp(self, stloc="", v1="", v2="", v3="", v4="", v5="", v6="", **kwargs): - """Defines the damping ratios as a function of mode. + def mdamp( + self, + stloc: str = "", + v1: str = "", + v2: str = "", + v3: str = "", + v4: str = "", + v5: str = "", + v6: str = "", + **kwargs, + ): + r"""Defines the damping ratios as a function of mode. - APDL Command: MDAMP + Mechanical APDL Command: `MDAMP `_ Parameters ---------- - stloc - Starting location in table for entering data. For example, if - STLOC = 1, data input in the V1 field applies to the first constant - in the table. If STLOC = 7, data input in the V1 field applies to - the seventh constant in the table, etc. Defaults to the last - location filled + 1. - - v1, v2, v3, . . . , v6 - Data assigned to six locations starting with STLOC. If a value is - already in this location, it will be redefined. Blank values for - V2 to V6 leave the corresponding previous value unchanged. + stloc : str + Starting location in table for entering data. For example, if ``STLOC`` = 1, data input in the + ``V1`` field applies to the first constant in the table. If ``STLOC`` = 7, data input in the + ``V1`` field applies to the seventh constant in the table, etc. Defaults to the last location + filled + 1. + + v1 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. + + v2 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. + + v3 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. + + v4 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. + + v5 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. + + v6 : str + Data assigned to six locations starting with ``STLOC``. If a value is already in this location, + it will be redefined. Blank values for ``V2`` to ``V6`` leave the corresponding previous value + unchanged. Notes ----- - Defines the damping ratios as a function of mode. Table position - corresponds to mode number. These ratios are added to the DMPRAT - value, if defined. Use STAT command to list current values. Applies - to the mode-superposition harmonic (ANTYPE,HARMIC), the mode- - superposition linear transient dynamic (ANTYPE,TRANS), and the spectrum - (ANTYPE,SPECTR) analyses. Repeat MDAMP command for additional - constants (10000 maximum). - - MDAMP can also be defined in a substructure analysis using component - mode synthesis with fixed-interface method (ANTYPE,SUBSTR with - CMSOPT,FIX and SEOPT,,,3). The damping ratios are added to the diagonal - of the reduced damping matrix as explained in Component Mode Synthesis - (CMS). + + .. _MDAMP_notes: + + Defines the damping ratios as a function of mode. Table position corresponds to mode number. These + ratios are added to the :ref:`dmprat` value, if defined. Use the :ref:`stat` command to list current + values. This command applies to mode-superposition harmonic ( :ref:`antype`,HARMIC), mode- + superposition linear transient dynamic ( :ref:`antype`,TRANS), and spectrum ( :ref:`antype`,SPECTR) + analyses. Repeat the :ref:`mdamp` command for additional constants (10000 maximum). + + :ref:`mdamp` can also be defined in a substructure analysis that uses component mode synthesis. The + damping ratios are added on the diagonal of the reduced damping matrix, as explained in `Component + Mode Synthesis (CMS) + `_ This command is also valid in PREP7. """ command = f"MDAMP,{stloc},{v1},{v2},{v3},{v4},{v5},{v6}" return self.run(command, **kwargs) - def mdplot(self, function="", dmpname="", scale="", **kwargs): - """Plots frequency-dependent modal damping coefficients calculated by + def mdplot(self, function: str = "", dmpname: str = "", scale: str = "", **kwargs): + r"""Plots frequency-dependent modal damping coefficients calculated by DMPEXT. - APDL Command: MDPLOT - DMPEXT. + Mechanical APDL Command: `MDPLOT `_ Parameters ---------- - function + function : str Function to display. - d_coeff - Damping coefficient + * ``d_coeff`` - Damping coefficient - s_coeff - Squeeze coefficient + * ``s_coeff`` - Squeeze coefficient - d_ratio - Damping ratio + * ``d_ratio`` - Damping ratio - s_ratio - Squeeze stiffness ratio + * ``s_ratio`` - Squeeze stiffness ratio - dmpname - Array parameter name where damping information is stored. Defaults - to d_damp. + dmpname : str + Array parameter name where damping information is stored. Defaults to :file:`d_damp`. - scale + scale : str Indicates whether to perform a linear or a double logarithmic plot. - LIN - Perform a linear plot. Default + * ``LIN`` - Perform a linear plot. Default - LOG - Perform a double logarithmic plot. + * ``LOG`` - Perform a double logarithmic plot. Notes ----- + + .. _MDPLOT_notes: + See Thin Film Analysis for more information on thin film analyses. """ command = f"MDPLOT,{function},{dmpname},{scale}" return self.run(command, **kwargs) - def midtol(self, key="", tolerb="", resfq="", **kwargs): - """Sets midstep residual criterion values for structural transient + def midtol(self, key: str = "", tolerb: str = "", resfq: str = "", **kwargs): + r"""Sets midstep residual criterion values for structural transient analyses. + + Mechanical APDL Command: `MIDTOL `_ - APDL Command: MIDTOL - analyses. + **Command default:** + For transient structural analysis, the out-of-balance residual is not checked at the midstep. Parameters ---------- - key + key : str Midstep residual criterion activation key. - ON or 1 - Activate midstep residual criterion in a structural transient analysis - (default). + * ``ON or 1`` - Activate midstep residual criterion in a structural transient analysis (default). - OFF or 0 - Deactivate midstep residual criterion in a structural transient analysis. + * ``OFF or 0`` - Deactivate midstep residual criterion in a structural transient analysis. - STAT - List the current midstep residual criterion setting. + * ``STAT`` - List the current midstep residual criterion setting. - tolerb - Midstep residual tolerance or reference value for bisection. - Defaults to 100 times the TOLER setting of the CNVTOL command. + tolerb : str + Midstep residual tolerance or reference value for bisection. Defaults to 100 times the ``TOLER`` + setting of the :ref:`cnvtol` command. - resfq - Key to use response frequency computation along with midstep - residual criterion for automatic time stepping (AUTOTS,ON). + If ``TOLERB`` > 0, it is used as a tolerance about the typical force and/or moment to compare + midstep residual force and/or moment for convergence. - OFF or 0 - Do not calculate response frequency and do not consider it in the automatic - time stepping (default). + If ``TOLERB`` < 0, it is used as a reference force value against which the midstep residual + force is compared for convergence. The reference force value is used to compute a reference + moment value for midstep residual moment comparison. - ON or 1 - Calculate response frequency and consider it in the automatic time stepping. + If midstep residual force and/or moment has not converged and :ref:`autots`,ON is used, then + ``TOLERB`` is also used to predict time step size for bisection. + + resfq : str + Key to use response frequency computation along with midstep residual criterion for automatic time + stepping ( :ref:`autots`,ON). + + * ``OFF or 0`` - Do not calculate response frequency and do not consider it in the automatic time + stepping (default). + + * ``ON or 1`` - Calculate response frequency and consider it in the automatic time stepping. Notes ----- - When TOLERB is input as a tolerance value (TOLERB > 0), the typical - force and/or moment from the regular time step is used in the midstep - residual force and/or moment comparison. - - In a structural transient analysis, the suggested tolerance range of - TOLERB (TOLERB > 0) is as follows: - - If the structural transient analysis is elastic and linear, and the - load is constant or changes slowly, use a smaller value of TOLERB to - achieve an accurate solution. If the analysis involves large amounts of - energy dissipation, such as elastic-plastic material, TOLERB can be - larger. If the analysis includes contact or rapidly varying loads, a - smaller value of TOLERB should be used if high frequency response is - important; otherwise, a larger value of TOLERB may be used to enable - faster convergence with larger time step sizes. - - For more information on how the midstep criterion is used by the - program, see Midstep Residual for Structural Dynamic Analysis in the - Mechanical APDL Theory Reference. + When ``TOLERB`` is input as a tolerance value ( ``TOLERB`` > 0), the typical force and/or moment + from the regular time step is used in the midstep residual force and/or moment comparison. + + In a structural transient analysis, the suggested tolerance range of ``TOLERB`` ( ``TOLERB`` > 0) is + as follows: + + * ``TOLERB`` = 1 to 10 times the ``TOLER`` setting of the :ref:`cnvtol` command for high accuracy + solution. + * ``TOLERB`` = 10 to 100 times the ``TOLER`` setting of the :ref:`cnvtol` command for medium + accuracy solution. + * ``TOLERB`` = more than 100 times the ``TOLER`` setting of the :ref:`cnvtol` command for low + accuracy solution. + If the structural transient analysis is elastic and linear, and the load is constant or changes + slowly, use a smaller value of + ``TOLERB`` to achieve an accurate solution. If the analysis involves large amounts of energy dissipation, such as elastic-plastic material, ``TOLERB`` can be larger. If the analysis includes contact or rapidly varying loads, a smaller value of ``TOLERB`` should be used if high frequency response is important; otherwise, a larger value of ``TOLERB`` may be used to enable faster convergence with larger time step sizes. + + For more information on how the midstep criterion is used by the program, see `Midstep Residual for + Structural Dynamic Analysis + `_ + in the `Mechanical APDL Theory Reference + `_. This command is also valid in PREP7. """ command = f"MIDTOL,{key},{tolerb},{resfq}" return self.run(command, **kwargs) - def modcont(self, mlskey="", enforcedkey="", **kwargs): - """Specify additional modal analysis options. + def modcont( + self, mlskey: str = "", enforcedkey: str = "", fastlv: str = "", **kwargs + ): + r"""Specify additional modal analysis options. - APDL Command: MODCONT + Mechanical APDL Command: `MODCONT `_ Parameters ---------- - mlskey + mlskey : str Multiple load step key: - OFF - Perform the modal analysis (compute the eigenvalues and the load vector) for - each load step. (default) + * ``OFF`` - Perform the modal analysis (compute the eigenvalues and the load vector) for each load + step. (default) - ON - Perform the modal analysis (compute the eigenvalues and the load vector) only - for the first load step; form the load vector for each - subsequent load step (without repeating the eigenvalue - calculations) and write all load vectors to the Jobname.MODE - file for downstream mode-superposition analyses. + * ``ON`` - Perform the modal analysis (compute the eigenvalues and the load vector) only for the + first load step; form the load vector for each subsequent load step (without repeating the + eigenvalue calculations) and write all load vectors to the :file:`Jobname.MODE` file for downstream + mode- superposition analyses. - enforcedkey + enforcedkey : str Enforced motion key: - OFF - Do not calculate enforced static modes. (default) - - ON - Calculate enforced static modes and write them to the Jobname.MODE file. + * ``OFF`` - Do not calculate enforced static modes. (default) - Notes - ----- - Specifies additional modal analysis (ANTYPE,MODAL) options. + * ``ON`` - Calculate enforced static modes and write them to the :file:`Jobname.MODE` file. - Use the LVSCALE command to apply the desired load in a mode- - superposition transient or harmonic analysis. + fastlv : str + Fast load vector generation key; valid only when ``MLSkey`` = ON: - The maximum number of load vectors that can be used in the downstream - mode-superposition transient or harmonic analysis is: 240. + * ``OFF`` - Do not activate fast load vector generation (default). - Generation of multiple loads (MLSkey = ON) is supported by the Block - Lanczos, PCG Lanczos, Supernode, Subspace, Unsymmetric, and QR damped - modal methods. + * ``ON`` - Activate fast load vector generation. This option is only supported when each load vector + is based on a unique element surface load ( :ref:`sfe` ) applied on one element, and the element + result superposition key is activated ( ``MSUPkey`` = YES on :ref:`mxpand` ). - The enforced motion calculation (EnforcedKey = ON) is supported by the - Block Lanczos and Supernode mode extraction methods. - """ - command = f"MODCONT,{mlskey},{enforcedkey}" - return self.run(command, **kwargs) + Notes + ----- - def modseloption( - self, dir1="", dir2="", dir3="", dir4="", dir5="", dir6="", **kwargs - ): - """APDL Command: MODSELOPTION + .. _MODCONT_notes: - Parameters - ---------- - dir1, dir2, dir3, dir4, dir5, dir6 - Selection of the direction to be expanded. + Specifies additional modal analysis ( :ref:`antype`,MODAL) options. - For ``modeselmethod=effm`` on the MXPAND command, the - directions correspond to the global Cartesian directions, - i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If dir1 = YES, - then any mode in this direction is expanded if its modal - effective mass divided by the total mass (modal effective mass - ratio) is greater than SIGNIF on the MXPAND command. If - dir1=NO, then the specified direction is not considered as a - criterion for expansion. If dir1 is given a numerical decimal - value, modes in that direction are selected (starting from the - ones with the largest modal effective mass ratios to the - smallest) until the sum of their modal effective mass ratio - equals this requested threshold. - - For ModeSelMethod = MODC on the MXPAND command, dir1 - corresponds to the first input spectrum, dir2 to the second, - etc. (i.e. for multiple spectrum inputs; the actual directions - correspond to their respective SED directions). If dir1=YES, - then any mode in this spectrum is ex- panded if its mode - coefficient divided by the largest mode coefficient is greater - than SIGNIF on the MXPAND command. If dir1=NO, then the - specified direction is not considered as a criterion for - expansion. + Use the :ref:`lvscale` command to apply the desired load in a mode-superposition transient or + harmonic analysis. - Notes - ----- - This command is only applicable when a mode selection method is defined - (ModeSelMethod on the MXPAND command). See Using Mode Selection in the - Mechanical APDL Structural Analysis Guide for more details. + When ``MSUPkey`` = YES on the :ref:`mxpand` command, the maximum number of load vectors allowed in + the :file:`Jobname.MODE` file defaults to 1000. To increase this limit, use the command + :ref:`config`,NUMLV. When ``FastLV`` = ON, the limit is automatically set to 1x10 :sup:`6` and + cannot be changed. - If a numerical value is specified for a direction, the significance - threshold (SIGNIF on the MXPAND command) is ignored for the selection - of the modes in this direction. + The maximum number of load vectors that can be used in the downstream mode-superposition transient + or harmonic analysis is the number of load vectors written in the :file:`Jobname.MODE` file. - If a mode is determined to be expanded in any of the 6 directions, it - will be expanded in the .MODE file. : Otherwise, the mode will not be - expanded. + `Generation of multiple loads + `_ ( + ``MLSkey`` = ON) is supported by the Block Lanczos, PCG Lanczos, Supernode, Subspace, Unsymmetric, + and QRDAMP mode extraction methods. - The default behavior is to consider all directions for expansion. + The `enforced motion calculation + `_ ( + ``EnforcedKey`` = ON) is supported by the Block Lanczos, Supernode, Subspace, and QRDAMP mode + extraction methods. """ - command = f"MODSELOPTION,{dir1},{dir2},{dir3},{dir4},{dir5},{dir6}" + command = f"MODCONT,{mlskey},{enforcedkey},,{fastlv}" return self.run(command, **kwargs) def modopt( self, - method="", - nmode="", - freqb="", - freqe="", - cpxmod="", - nrmkey="", - modtype="", - blocksize="", - freqmod="", + method: str = "", + nmode: str = "", + freqb: str = "", + freqe: str = "", + cpxmod: str = "", + nrmkey: str = "", + modtype: str = "", + blocksize: str = "", + freqmod: str = "", **kwargs, ): - """Specifies modal analysis options. + r"""Specifies modal analysis options. - APDL Command: MODOPT + Mechanical APDL Command: `MODOPT `_ Parameters ---------- - method + method : str Mode-extraction method to be used for the modal analysis. - LANB - Block Lanczos + * ``LANB`` - Block Lanczos + + * ``LANPCG`` - PCG Lanczos + + * ``SNODE`` - Supernode modal solver + + * ``SUBSP`` - Subspace algorithm + + * ``UNSYM`` - Unsymmetric matrix + + * ``DAMP`` - Damped system - LANPCG - PCG Lanczos + * ``QRDAMP`` - Damped system using QR algorithm - SNODE - Supernode modal solver + nmode : str + The number of modes to extract. The value can depend on the value supplied for ``Method``. ``NMODE`` + has no default and must be specified. If ``Method`` = LANB, LANPCG, or SNODE, the number of modes + that can be extracted can equal the DOFs in the model after the application of all boundary + conditions. - SUBSP - Subspace algorithm + For ``Method`` = LANB, SUBSP and UNSYM, you can specify ``NMODE`` = ALL to extract all eigenvalues + in a given frequency range. To use this option, you must also define the frequency range (that is, a + ``FREQE`` value must be set). - UNSYM - Unsymmetric matrix + Recommendation: - DAMP - Damped system + * When ``Method`` = LANPCG, ``NMODE`` should be less than 100 to be computationally efficient. + * When ``Method`` = SNODE, ``NMODE`` should be greater than 100 for 2D plane or 3D shell/beam models + and greater than 250 for 3D solid elements to be computationally efficient. - QRDAMP - Damped system using QR algorithm + freqb : str + The beginning, or lower end, of the frequency range (or eigenvalue range if ``FREQMOD`` is + specified) of interest. - VT - Variational Technology + For ``Method`` = LANB, SUBSP, UNSYM, DAMP, and QRDAMP, ``FREQB`` also represents the first shift + point for the eigenvalue iterations. For UNSYM and DAMP, the default = -1.0 For other methods, + the default is calculated internally. - nmode - The number of modes to extract. The value can depend on the value - supplied for Method. NMODE has no default and must be specified. If - Method = LANB, LANPCG, or SNODE, the number of modes that can be - extracted can equal the DOFs in the model after the application of - all boundary conditions. + Eigenvalue extraction is most accurate near the shift point. Multiple shift points are used + internally in the LANB, SUBSP, UNSYM, and QRDAMP methods. For the LANB, LANPCG, SUBSP, UNSYM, + DAMP, and QRDAMP methods with a positive ``FREQB`` value, eigenvalues are output beginning at + the shift point and increase in magnitude. For the UNSYM and DAMP methods with a negative + ``FREQB`` value, eigenvalues are output beginning at zero magnitude and increase. - freqb - The beginning, or lower end, of the frequency range of interest. + Choosing higher ``FREQB`` values with the LANPCG and SNODE methods may lead to inefficient + solution times because these methods will find all eigenvalues between zero and ``FREQB`` before + finding the requested modes between ``FREQB`` and ``FREQE``. - freqe - The ending, or upper end, of the frequency range of interest (in - Hz). The default for Method = SNODE is described below. The default - for all other methods is to calculate all modes, regardless of - their maximum frequency. + freqe : str + The ending, or upper end, of the frequency range (or eigenvalue range if ``FREQMOD`` is + specified) of interest (in Hz). Default = 100 Hz when ``Method`` = SNODE. The default for all + other methods is to calculate all modes, regardless of their maximum frequency. - cpxmod - Complex eigenmode key. (Valid only when Method = QRDAMP or Method = - UNSYM). + To maintain solution efficiency, do not set the ``FREQE`` value too high; for example, not + higher than 5000 Hz for an industrial problem. The higher the ``FREQE`` value used for the SNODE + method, the more accurate the solution and the more eigenvalues produced; however, the solution + time also increases. For example, if ``FREQE`` is set to 1e8, it causes the underlying + supernodal structures to find all possible eigenvalues of each group of supernodes, requiring + excessive solution time. The accuracy of the SNODE solution is controlled by ``FREQE`` and by + the ``RangeFact`` value on the :ref:`snoption` command. - AUTO - Determine automatically if the eigensolutions are real or complex and output - them accordingly. This is the default for Method = UNSYM. - Not supported for Method = QRDAMP. + cpxmod : str + Complex eigenmode key. (Valid only when ``Method`` = QRDAMP or ``Method`` = UNSYM). - ON or CPLX - Calculate and output complex eigenmode shapes. + * ``AUTO`` - Determine automatically if the eigensolutions are real or complex and output them + accordingly (default when ``Method`` = UNSYM). Not supported for ``Method`` = QRDAMP. - OFF or REAL - Do not calculate complex eigenmode shapes. This is required if a mode- - superposition analysis is intended after the modal - analysis for Method = QRDAMP. This is the default for - this method. + * ``ON or CPLX`` - Calculate and output complex eigenmode shapes. - nrmkey + * ``OFF or REAL`` - Do not calculate complex eigenmode shapes (default). This setting is required if + a mode- superposition analysis is intended after the modal analysis for ``Method`` = QRDAMP. + + nrmkey : str Mode shape normalization key: - OFF - Normalize the mode shapes to the mass matrix (default). - - ON - Normalize the mode shapes to unity instead of to the mass matrix. If a - subsequent spectrum or mode-superposition analysis is planned, - the mode shapes should be normalized to the mass matrix - (Nrmkey = OFF). - - modtype - Type of modes calculated by the eigensolver. Only applicable to the - unsymmetric eigensolver. - - Blank - Right eigenmodes. This value is the default. - - BOTH - Right and left eigenmodes. The left eigenmodes are written to Jobname.LMODE. - This option must be activated if a mode-superposition - analysis is intended. - - blocksize - The block vector size to be used with the Block Lanczos or - Subspace eigensolver (used only when Method = LANB or - SUBSP). BlockSize must be an integer value between 0 and - 16. When BlockSize = zero or blank, the code decides the - block size internally (normally, a value of 8 is used for - LANB and a value of 6 is used for SUBSP). Typically, - higher BlockSize values are more efficient under each of - the following conditions: - - - When running in out-of-core mode and there is not enough - physical memory to buffer all of the files written by - the Block Lanczos or Subspace eigensolver (and thus, the - time spent doing I/O is considerable). - - Many modes are requested (>100). - - Higher-order solid elements dominate the model. - - The memory usage only slightly increases as BlockSize is - increased. It is recommended that you use a value - divisible by 4 (4, 8, 12, or 16). - - freqmod - The specified frequency when the solved eigenvalues are no - longer frequencies (for example, the model has the Floquet - periodic boundary condition). In a modal analysis, the - Floquet periodic boundary condition (body load FPBC) is - only valid for the acoustic elements FLUID30, FLUID220, - and FLUID221. + * ``OFF`` - Normalize the mode shapes to the mass matrix (default). This option is invalid for + damped modal cyclic symmetry ( ``Method`` = DAMP or QRDAMP with the :ref:`cyclic` command). + + * ``ON`` - Normalize the mode shapes to unity instead of to the mass matrix (default for damped + modal cyclic symmetry [ ``Method`` = DAMP or QRDAMP with the :ref:`cyclic` command]). + + If a subsequent spectrum or mode-superposition analysis is planned, the mode shapes should be + normalized to the mass matrix ( ``Nrmkey`` = OFF). + + modtype : str + Type of modes calculated by the eigensolver. Only applicable to the unsymmetric eigensolver. + + * ```` - Right eigenmodes (default). + + * ``BOTH`` - Right and left eigenmodes. The left eigenmodes are written to :file:`Jobname.LMODE`. + This option must be activated if a mode-superposition analysis is intended. + + blocksize : str + The block vector size to be used with the Block Lanczos or Subspace eigensolver (used only when ``Method`` = LANB or SUBSP). ``BlockSize`` must be an integer value between 0 and 16. When BlockSize = zero or blank, the code decides the block size internally (normally, a value of 8 is used for LANB and a value of 6 is used for SUBSP). Typically, higher ``BlockSize`` values are more efficient under each of the following conditions: + + * When running in out-of-core mode and there is not enough physical memory to buffer all of the + files written by the Block Lanczos or Subspace eigensolver (and thus, the time spent doing I/O is + considerable). + + * Many modes are requested (>100). + + * Higher-order solid elements dominate the model. + + The memory usage only slightly increases as + ``BlockSize`` is increased. It is recommended that you use a value divisible by 4 (4, 8, 12, or 16). + + freqmod : str + The specified frequency when the solved eigenvalues are no longer frequencies (for example, the + model has the Floquet periodic boundary condition). In a modal analysis, the Floquet periodic + boundary condition (body load FPBC) is only valid for the acoustic elements ``FLUID30``, + ``FLUID220``, and ``FLUID221``. Notes ----- - Specifies modal analysis (ANTYPE,MODAL) options. Additional options - used only for the Supernode (SNODE) eigensolver are specified by the - SNOPTION command. Additional options used only for the Subspace (SUBSP) - eigensolver are specified by the SUBOPT command. If Method = LANPCG, - ANSYS automatically switches to the PCG solver internally for this - modal analysis. You can further control the efficiency of the PCG - solver with the PCGOPT and EQSLV commands. - - For models that involve a non-symmetric element stiffness matrix, as in - the case of a contact element with frictional contact, the QRDAMP - eigensolver (MODOPT, QRDAMP) extracts modes in the modal subspace - formed by the eigenmodes from the symmetrized eigenproblem. The QRDAMP - eigensolver symmetrizes the element stiffness matrix on the first pass - of the eigensolution, and in the second pass, eigenmodes are extracted - in the modal subspace of the first eigensolution pass. For such non- - symmetric eigenproblems, you should verify the eigenvalue and eigenmode - results using the non-symmetric matrix eigensolver (MODOPT,UNSYM). - - The DAMP and QRDAMP options cannot be followed by a subsequent spectrum - analysis. The UNSYM method supports spectrum analysis when - eigensolutions are real. + + .. _MODOPT_notes: + + Specifies modal analysis ( :ref:`antype`,MODAL) options. + + Additional options for specific eigensolvers are controlled by these commands: + + * :ref:`snoption` specifies options for the Supernode (SNODE) eigensolver. + + * :ref:`subopt` specifies options for the Subspace (SUBSP) eigensolver. + + * :ref:`qrdopt` specifies options for the QRDAMP eigensolver. + + * :ref:`dampopt` specifies options for the damped (DAMP) eigensolver. + + * :ref:`lanboption` specifies options for the Block Lanczos (LANB) eigensolver. For more difficult + modal problems, you can specify an alternative version of the Block Lanczos eigensolver ( + :ref:`lanboption`, ALT1). + + If ``Method`` = LANPCG, Mechanical APDL automatically switches to the PCG solver internally for this + modal + analysis. You can further control the efficiency of the PCG solver with the :ref:`pcgopt` and + :ref:`eqslv` commands. + + For models that involve a non-symmetric element stiffness matrix, as in the case of a contact + element with frictional contact, the QRDAMP eigensolver ( :ref:`modopt`, QRDAMP) extracts modes in + the modal subspace formed by the eigenmodes from the symmetrized eigenproblem. The QRDAMP + eigensolver symmetrizes the element stiffness matrix on the first pass of the eigensolution, and in + the second pass, eigenmodes are extracted in the modal subspace of the first eigensolution pass. For + such non-symmetric eigenproblems, you should verify the eigenvalue and eigenmode results using the + non-symmetric matrix eigensolver ( :ref:`modopt`,UNSYM). + + The DAMP and QRDAMP options cannot be followed by a subsequent spectrum analysis. The UNSYM method + supports spectrum analysis when eigensolutions are real. + + In a modal analysis, the Floquet periodic boundary condition (body load FPBC) is only valid for the + acoustic elements ``FLUID30``, ``FLUID220``, and ``FLUID221``. + + For more details about mode shape normalization, see `Description of Analysis for Symmetric Undamped + Systems + `_ This command is also valid in PREP7. - Distributed ANSYS Restriction: The VT extraction method is not - supported in Distributed ANSYS. All other extraction methods are - supported. However, PCG Lanczos, SUBSP, UNSYM, DAMP, and QRDAMP are the - only distributed eigensolvers that will run a fully distributed - solution. The Block Lanczos and Supernode eigensolvers are not - distributed eigensolvers; therefore, you will not see the full - performance improvements with these methods that you would with a fully - distributed solution. + Distributed-Memory Parallel (DMP) Restriction All extraction methods are supported in a DMP + solution. Block Lanczos, PCG Lanczos, SUBSP, UNSYM, + DAMP, and QRDAMP are distributed eigensolvers that run a fully distributed solution. However, the + Supernode eigensolver is not a distributed eigensolver; therefore, you will not see the full + performance improvements with this method that you would with a fully distributed solution. + + .. _MODOPT_extranote1: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. """ command = f"MODOPT,{method},{nmode},{freqb},{freqe},{cpxmod},{nrmkey},{modtype},{blocksize},,,,{freqmod}" return self.run(command, **kwargs) + def modseloption( + self, + dir1: str = "", + dir2: str = "", + dir3: str = "", + dir4: str = "", + dir5: str = "", + dir6: str = "", + **kwargs, + ): + r"""Specifies the criteria for selecting the modes to be expanded. + + Mechanical APDL Command: `MODSELOPTION `_ + + Parameters + ---------- + dir1 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + dir2 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + dir3 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + dir4 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + dir5 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + dir6 : str + Selection of the direction to be expanded. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, the directions correspond to the + global Cartesian directions, i.e. 1=X, 2=Y, 3=Z, 4=ROTX, 5=ROTY, and 6=ROTZ. If ``dir1`` = YES, + then any mode in this direction is expanded if its modal effective mass divided by the total + mass (modal effective mass ratio) is greater than ``SIGNIF`` on the :ref:`mxpand` command. If + ``dir1`` =NO, then the specified direction is not considered as a criterion for expansion. If + ``dir1`` is given a numerical decimal value, modes in that direction are selected (starting from + the ones with the largest modal effective mass ratios to the smallest) until the sum of their + modal effective mass ratio equals this requested threshold. + + For ``ModeSelMethod`` = MODC on the :ref:`mxpand` command, ``dir1`` corresponds to the first + input spectrum, ``dir2`` to the second, etc. (i.e. for multiple spectrum inputs; the actual + directions correspond to their respective SED directions). If ``dir1`` =YES, then any mode in + this spectrum is expanded if its mode coefficient divided by the largest mode coefficient is + greater than SIGNIF on the :ref:`mxpand` command. If ``dir1`` =NO, then the specified direction + is not considered as a criterion for expansion. + + Notes + ----- + + .. _MODSELOPTION_notes: + + This command is only applicable when a mode selection method is defined ( ``ModeSelMethod`` on the + :ref:`mxpand` command). See `Using Mode Selection + `_ + + If a numerical value is specified for a direction, the significance threshold (SIGNIF on the + :ref:`mxpand` command) is ignored for the selection of the modes in this direction. + + If a mode is determined to be expanded in **any** of the 6 directions, it will be expanded in the + :file:`.MODE` file. Otherwise, the mode will not be expanded. + + The default behavior is to consider all directions for expansion. + + For ``ModeSelMethod`` = EFFM on the :ref:`mxpand` command, ``dir4``, ``dir5``, and ``dir6`` are not + considered if mass related information have been calculated using the lumped approximation instead + of the precise calculation (See `Mass Related Information + `_ + """ + command = f"MODSELOPTION,{dir1},{dir2},{dir3},{dir4},{dir5},{dir6}" + return self.run(command, **kwargs) + def mxpand( self, - nmode="", - freqb="", - freqe="", - elcalc="", - signif="", - msupkey="", - modeselmethod="", + nmode: str = "", + freqb: str = "", + freqe: str = "", + elcalc: str = "", + signif: str = "", + msupkey: str = "", + modeselmethod: str = "", + engcalc: str = "", **kwargs, ): - """Specifies the number of modes to expand and write for a modal or + r"""Specifies modal or buckling analysis expansion options. - APDL Command: MXPAND - buckling analysis. + Mechanical APDL Command: `MXPAND `_ Parameters ---------- - nmode - Number of modes or array name (enclosed in percent signs) to expand - and write. If blank or ALL, expand and write all modes within the - frequency range specified. If -1, do not expand and do not write - modes to the results file during the analysis. If an array name is - input, the array must contain 1 for the expanded modes and zero - otherwise, where the array index corresponds to the mode number. To - specify an array containing the individual modes to expand, enclose - the array name in percent (%) signs (for example, - MXPAND,%arrname%). Use the ``*DIM`` command to define the array. - - freqb - Beginning, or lower end, of frequency range of interest. If FREQB - and FREQE are both blank, expand and write the number of modes - specified without regard to the frequency range. Defaults to the - entire range. - - freqe + nmode : str + Number of modes or array name (enclosed in percent signs) to expand and write. If blank or ALL, + expand and write all modes within the frequency range specified. If -1, do not expand and do not + write modes to the results file during the analysis. If an array name is input, the array must + contain 1 for the expanded modes and zero otherwise, where the array index corresponds to the + mode number. To specify an array containing the individual modes to expand, enclose the array + name in percent (%) signs (for example, :ref:`mxpand`,%arrname%). Use the :ref:`dim` command to + define the array. + + freqb : str + Beginning, or lower end, of frequency range of interest. If ``FREQB`` and ``FREQE`` are both + blank, expand and write the number of modes specified without regard to the frequency range. + Defaults to the entire range. + + freqe : str Ending, or upper end, of frequency range of interest. - elcalc + elcalc : str Element calculation key: - NO - Do not calculate element results, reaction forces, and energies (default). + * ``NO`` - Do not calculate element results, reaction forces, and energies (default). + + * ``YES`` - Calculate element results, reaction forces, energies, and the nodal degree of freedom + solution. + + signif : str + Expand only those modes whose significance level exceeds the ``SIGNIF`` threshold (only + applicable when ``ModeSelMethod`` is defined). + + If ``ModeSelMethod`` = MODC, the significance level of a mode is defined as the mode coefficient + divided by the maximum mode coefficient of all modes. + + If ``ModeSelMethod`` = EFFM, the significance level of a mode is defined as the modal effective + mass, divided by the total mass. - YES - Calculate element results, reaction forces, energies, and the nodal degree of - freedom solution. + If ``ModeSelMethod`` = DDAM, the significance level of a mode is defined as the modal effective + weight, divided by the total weight. - signif - Expand only those modes whose significance level exceeds the SIGNIF - threshold (only applicable when ModeSelMethod is defined). + Any mode whose significance level is less than ``SIGNIF`` is considered insignificant and is not + expanded. The higher the ``SIGNIF`` threshold, the fewer the number of modes expanded. + ``SIGNIF`` defaults to 0.001, except for the case of DDAM mode selection method where it + defaults to 0.01. If ``SIGNIF`` is specified as 0.0, it is taken as 0.0. - msupkey + msupkey : str Element result superposition key: - NO - Do not write element results to the mode file Jobname.MODE. + * ``NO`` - Do not write element results to the mode file :file:`Jobnamemode`. + + * ``YES`` - Write element result to the mode file for use in the expansion pass of a subsequent mode- + superposition PSD, spectrum, transient, or harmonic analysis. This value is the default if all of + the following conditions exist: + + * ``Elcalc`` = YES. + + * The mode shapes are normalized to the mass matrix. + + * ``FREQB`` and ``FREQE`` are blank or 0.0. + + * No superelement is defined. - YES - Write element result to the mode file for use in the expansion pass of a - subsequent mode-superposition PSD, transient, or harmonic - analysis (default if Elcalc = YES and the mode shapes are - normalized to the mass matrix). + modeselmethod : str + Methods for mode selection (not supported for complex eigensolvers): - modeselmethod - Methods for mode selection (not supported for complex - eigensolvers): + * ```` - No mode selection is performed (default). - blank - No mode selection is performed (default). + * ``EFFM`` - The mode selection is based on the modal effective masses. - MODM - The mode selection is based on the modal effective masses. + * ``MODC`` - The mode selection is based on the mode coefficients. - MODC - The mode selection is based on the mode coefficients. + * ``DDAM`` - The mode selection is based on DDAM procedure (see `Mode Selection Based on the DDAM + Method `_ - DDAM - The mode selection is based on DDAM procedure (see Mode Selection Based on DDAM - Procedure in the Mechanical APDL Structural Analysis Guide - for more information). This option is applicable only to - DDAM spectrum analysis. + engcalc : str + Additional element energies calculation key: + + * ``NO`` - Do not calculate additional energies (default). + + * ``YES`` - Calculate average, amplitude, and peak values for the following: stiffness and kinetic + energies, and damping energy. Notes ----- - Specifies the number of modes to expand and write over a frequency - range for a modal (ANTYPE,MODAL) or buckling (ANTYPE,BUCKLE) analysis. - If used in SOLUTION, this command is valid only within the first load - step. - - There is no limit on the number of expanded modes (NMODE). However, - there is a limit on the maximum number of modes used via the ``*GET,,MODE`` - command, mode combinations, and the MDAMP command. - - With MSUPkey = YES, the computed element results (Elcalc = YES) are - written to Jobname.MODE for use in subsequent downstream mode- - superposition analyses, including harmonic, transient, and PSD - analyses. This significantly reduces computation time for the - combination or expansion passes. For limitations, see Option: Number of - Modes to Expand (MXPAND) in the Mechanical APDL Structural Analysis - Guide. - - If a mode selection method (ModeSelMethod) is defined, only the - selected modes will be expanded. See Using Mode Selection in the - Mechanical APDL Structural Analysis Guide for more details about the - procedure. - - For array input (NMODE), the array must be dimensioned to be the size - of the number of modes extracted (NMODE on the MODOPT command). A value - of 1 in the array indicates the mode is to be expanded, and a value of - 0 indicates not to expand the mode. For the DAMP modal solution, the - modes are in pairs, so be sure to verify that both modes of a pair have - the same value. (For example, if modes #3 and #4 are a pair, indices 3 - and 4 in the array should have the same value, 0 or 1.) - - For linear perturbation modal analyses, you must set both Elcalc and - MSUPkey to YES so that the downstream stress expansion pass can produce - a solution consistent with the linear or nonlinear base (static or full - transient) analysis. The prestressed nonlinear element history (saved - variables) is accessible only in the first and second phases of the - linear perturbation. The downstream MSUP or PSD analysis can only reuse - the nonlinear information contained in the Jobname.MODE file that is - generated in the linear perturbation. - - In a Distributed ANSYS analysis, you must issue MXPAND to specify the - number of modes to expand when computing the modes and mode shapes. In - a Distributed ANSYS run, MXPAND cannot be issued in an expansion pass - (EXPASS). + + .. _MXPAND_notes: + + Specifies the number of modes to expand and write over a frequency range for a modal ( :ref:`antype` + ,MODAL) or buckling ( :ref:`antype`,BUCKLE) analysis. If used in SOLUTION, this command is valid + only within the first load step. + + There is no limit on the number of expanded modes ( ``NMODE`` ). However, there is a limit on the + maximum number of modes used via the :ref:`get`, MODE command, mode combinations, and the + :ref:`mdamp` command. + + With ``MSUPkey`` = YES, the computed element results ( ``Elcalc`` = YES) are written to + :file:`Jobname.mode` for use in subsequent downstream mode-superposition analyses, including + harmonic, transient, and all spectrum analyses. This significantly reduces computation time for the + combination or expansion passes. For limitations and available elemental results, see. + + The calculation of additional energies ( ``EngCalc`` = YES) is valid only for ``Method`` = DAMP on + the :ref:`modopt` command and ``Method`` = QRDAMP with ``Cpxmod`` = CPLX on the :ref:`modopt` + command. + + If a mode selection method ( ``ModeSelMethod`` ) is defined, only the selected modes will be + expanded. See `Using Mode Selection + `_ + + For array input ( ``NMODE`` ), the array must be dimensioned to be the size of the number of modes + extracted ( ``NMODE`` on the :ref:`modopt` command). A value of 1 in the array indicates the mode is + to be expanded, and a value of 0 indicates not to expand the mode. For the DAMP modal solution, the + modes are in pairs, so be sure to verify that both modes of a pair have the same value. (For + example, if modes #3 and #4 are a pair, indices 3 and 4 in the array should have the same value, 0 + or 1.) + + For `linear perturbation + `_ modal + analyses, you must set both ``Elcalc`` and ``MSUPkey`` to YES so that the downstream stress + expansion pass can produce a solution consistent with the linear or nonlinear base (static or full + transient) analysis. The prestressed nonlinear element history (saved variables) is accessible only + in the first and second phases of the linear perturbation. The downstream mode superposition + analysis (such as MSUP or PSD) can only reuse the nonlinear information contained in the + :file:`Jobname.mode` file that is generated in the linear perturbation. + + In a distributed-memory parallel (DMP) analysis, you must issue :ref:`mxpand` to specify the number + of modes to expand when computing the modes and mode shapes. In a DMP run, :ref:`mxpand` cannot be + issued in an expansion pass ( :ref:`expass` ). This command is also valid in PREP7. """ - command = f"MXPAND,{nmode},{freqb},{freqe},{elcalc},{signif},{msupkey},{modeselmethod}" + command = f"MXPAND,{nmode},{freqb},{freqe},{elcalc},{signif},{msupkey},{modeselmethod},{engcalc}" return self.run(command, **kwargs) - def qrdopt(self, reusekey="", symmeth="", cmccoutkey="", **kwargs): - """Specifies additional QRDAMP modal analysis options. + def qrdopt( + self, reusekey: str = "", symmeth: str = "", cmccoutkey: str = "", **kwargs + ): + r"""Specifies additional QRDAMP modal analysis options. - APDL Command: QRDOPT + Mechanical APDL Command: `QRDOPT `_ Parameters ---------- - reusekey - Reuse key for method=QRDAMP specified in MODOPT command. + reusekey : str + Reuse key for method= ``QRDAMP`` specified in :ref:`modopt` command. - ON - Reuse the symmetric eigensolution from the previous - load steps or from the previous solution. + * ``ON`` - Reuse the symmetric eigensolution from the previous load steps or from the previous + solution. - OFF - Do not reuse (calculates symmetric eigensolution at - current load step). This is the default. + * ``OFF`` - Do not reuse (calculates symmetric eigensolution at current load step). This is the + default. - symmeth - Mode-extraction method to be used for the symmetric eigenvalue - problem. + symmeth : str + Mode-extraction method to be used for the symmetric eigenvalue problem. - LANB - Block Lanczos (default for shared-memory parallel processing). + * ``LANB`` - Block Lanczos algorithm (default). - SUBSP - Subspace algorithm (default for distributed-memory - parallel processing). + * ``SUBSP`` - Subspace algorithm. - cmccoutkey - Complex Modal Contribution Coefficients (CMCC) output - key. See Calculate the Complex Mode Contribution - Coefficients (CMCC) in the Structural Analysis Guide for - details and usage. + * ``SNODE`` - Supernode algorithm. - ON - Output the CMCC to the text file Jobname.CMCC. + cmccoutkey : str + Complex Modal Contribution Coefficients (CMCC) output key. See `Calculate the Complex Mode Contribution Coefficients (CMCC) `_ - OFF - Do not output the CMCC. This is the default. + * ``ON`` - Output the CMCC to the text file :file:`JobnameCMCC`. + + * ``OFF`` - Do not output the CMCC. This is the default. Notes ----- - If the filename.modesym file exists in the working directory - and ReuseKey = ON, filename.modesym will be reused. If - filename.modesym does not exist in the working directory, the - symmetric eigensolution will be calculated. - - When ReuseKey=ON, both the new modal analysis - (filename.modesym usage) and the preceding modal analysis - (filename.modesym generation) must be performed using the same - product version number. - The mode-extraction method changes depending on the type of - parallelism involved. For performance reasons, the subspace - method is used with distributed-memory parallel processing - (Distributed ANSYS) runs, while the Block Lanczos method is - used with shared-memory parallel processing runs. + .. _QRDOPT_notes: + + If the :file:`filename.modesym` file exists in the working directory and ``ReuseKey`` = ON, + :file:`filename.modesym` will be reused. If :file:`filename.modesym` does not exist in the working + directory, the symmetric eigensolution will be calculated. + + When ``ReuseKey`` =ON, both the new modal analysis ( :file:`filename.modesym` usage) and the + preceding modal analysis ( :file:`filename.modesym` generation) must be performed using the same + product version number. """ - return self.run(f"QRDOPT,{reusekey},,,{symmeth},{cmccoutkey}", **kwargs) + command = f"QRDOPT,{reusekey},,,{symmeth},{cmccoutkey}" + return self.run(command, **kwargs) - def rigid(self, dof1="", dof2="", dof3="", dof4="", dof5="", dof6="", **kwargs): - """Specifies known rigid body modes (if any) of the model. + def rigid( + self, + dof1: str = "", + dof2: str = "", + dof3: str = "", + dof4: str = "", + dof5: str = "", + dof6: str = "", + **kwargs, + ): + r"""Specifies known rigid body modes (if any) of the model. - APDL Command: RIGID + Mechanical APDL Command: `RIGID `_ Parameters ---------- - dof1, dof2, dof3, . . . , dof6 - Up to six global Cartesian directions of the rigid modes. - For a completely free 2-D model, use ALL or UX, UY, ROTZ. - For a completely free 3-D model, use ALL or UX, UY, UZ, - ROTX, ROTY, ROTZ. For a constrained model, use UX, UY, - UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each - and every unconstrained direction which exists in the - model (not specifying every direction may cause - difficulties in extracting the modes). + dof1 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). + + dof2 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). + + dof3 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). + + dof4 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). + + dof5 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). + + dof6 : str + Up to six global Cartesian directions of the rigid modes. For a completely free 2D model, use + ALL or UX, UY, ROTZ. For a completely free 3D model, use ALL or UX, UY, UZ, ROTX, ROTY, ROTZ. + For a constrained model, use UX, UY, UZ, ROTX, ROTY, or ROTZ, as appropriate, to specify each + and every unconstrained direction which exists in the model (not specifying every direction may + cause difficulties in extracting the modes). Notes ----- - Specifies known rigid body modes (if any) of the model. This - command applies only to a component mode synthesis (CMS) - analysis (see the CMSOPT command). Any rigid body modes - specified must be permitted by the applied displacement - constraints (i.e., do not specify a rigid body mode in a - constrained direction). Reissue the command to redefine the - specification. If used in SOLUTION, this command is valid - only within the first load step. - This command is also valid in PREP7. + .. _RIGID_notes: + + Specifies known rigid body modes (if any) of the model. This command applies only to a component + mode synthesis (CMS) analysis (see the :ref:`cmsopt` command). Any rigid body modes specified must + be permitted by the applied displacement constraints (that is, do not specify a rigid body mode in a + constrained direction). Reissue the command to redefine the specification. If used in SOLUTION, this + command is valid only within the first load step. - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + This command is also valid in PREP7. Distributed-Memory Parallel (DMP) Restriction This command is + not supported in a DMP solution. """ command = f"RIGID,{dof1},{dof2},{dof3},{dof4},{dof5},{dof6}" return self.run(command, **kwargs) - def subopt(self, option="", value1="", **kwargs): - """Specifies Subspace (SUBSP) eigensolver options. + def subopt(self, option: str = "", value1: str = "", **kwargs): + r"""Specifies Subspace (SUBSP) eigensolver options. - APDL Command: SUBOPT + Mechanical APDL Command: `SUBOPT `_ Parameters ---------- - option + option : str One of the following options: - STRMCK - Controls whether a Sturm sequence check is performed. - Valid input for Value1 when Option = STRMCK: + * ``STRMCK`` - Controls whether a Sturm sequence check is performed. - OFF - Do not perform Sturm sequence check (default). + Valid input for ``Value1`` when ``Option`` = STRMCK: - ON - Perform Sturm sequence check. + * ``OFF`` - Do not perform Sturm sequence check (default). - MEMORY - Controls the memory allocation strategy for the Subspace eigensolver. - Valid input for Value1 when Option = MEMORY: + * ``ON`` - Perform Sturm sequence check. - AUTO - Use the default memory allocation strategy (``default``). + * ``MEMORY`` - Controls the memory allocation strategy for the Subspace eigensolver. - INCORE - Force the Subspace eigensolver to allocate in-core memory. + Valid input for ``Value1`` when ``Option`` = MEMORY: - MIX1 - First level of mixed in-core / out-of-core configuration. + * ``DEFAULT`` - Default memory configuration (default). Everything is determined dynamically with + respect to current machine resources. - MIX2 - Second level of mixed in-core / out-of-core configuration. + * ``INCORE`` - Fully in-core memory configuration. - OUTOFCORE - Force the Subspace eigensolver to use scratch files. + * ``MIX1`` - First level of mixed in-core / out-of-core configuration. - Value1 - Assigned value for the specified Option (as described above). + * ``MIX2`` - Second level of mixed in-core / out-of-core configuration. + + * ``OUTOFCORE`` - Fully out-of-core memory configuration. + + value1 : str + Assigned value for the specified ``Option`` (as described above). Notes ----- - ``SUBOPT`` specifies options to be used with the Subspace eigensolver - (``MODOPT,SUBSP``) during a modal analysis. + + .. _SUBOPT_notes: + + :ref:`subopt` specifies options to be used with the Subspace eigensolver ( :ref:`modopt`,SUBSP) + during a modal analysis. + + **Memory Allocation Option (** ``Option`` = MEMORY) + + The Subspace eigensolver algorithm allocates two main pools of memory: + + Memory for the internal subspace eigensolver iterations. + + Memory for the specific subspace eigensolver working arrays. + + The following table shows how memory is allocated for each option. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + The MIX1 configuration typically uses more memory than the MIX2 configuration, except when a large + number of modes are requested for a small model. """ command = f"SUBOPT,{option},{value1}" return self.run(command, **kwargs) - def timint(self, key="", lab="", **kwargs): - """Turns on transient effects. + def timint(self, key: str = "", lab: str = "", **kwargs): + r"""Turns on transient effects. - APDL Command: TIMINT + Mechanical APDL Command: `TIMINT `_ Parameters ---------- - key + key : str Transient effects key: - OFF - No transient effects (static or steady-state). + * ``OFF`` - No transient effects (static or steady-state). - ON - Include transient (mass or inertia) effects. + * ``ON`` - Include transient (mass or inertia) effects. - lab + lab : str Degree of freedom label: - ALL - Apply this key to all appropriate labels (default). + * ``ALL`` - Apply this key to all appropriate labels (default). - STRUC - Apply this key to structural DOFs. + * ``STRUC`` - Apply this key to structural DOFs. - THERM - Apply this key to thermal DOFs. + * ``THERM`` - Apply this key to thermal DOFs. - ELECT - Apply this key to electric DOFs. + * ``ELECT`` - Apply this key to electric DOFs. - MAG - Apply this key to magnetic DOFs. + * ``MAG`` - Apply this key to magnetic DOFs. - FLUID - Apply this key to fluid DOFs. + * ``FLUID`` - Apply this key to fluid DOFs. - DIFFU - Apply this key to concentration of DOFs. + * ``DIFFU`` - Apply this key to concentration of DOFs. Notes ----- - Indicates whether this load step in a full transient analysis should - use time integration, that is, whether it includes transient effects - (e.g. structural inertia, thermal capacitance) or whether it is a - static (steady-state) load step for the indicated DOFs. Transient - initial conditions are introduced at the load step having Key = ON. - Initial conditions are then determined from the previous two substeps. - Zero initial velocity and acceleration are assumed if no previous - substeps exist. See the Structural Analysis Guide, the Thermal - Analysis Guide, and the Low-Frequency Electromagnetic Analysis Guide - for details. + + .. _TIMINT_notes: + + Indicates whether this load step in a full transient analysis should use time integration, that is, + whether it includes transient effects (e.g. structural inertia, thermal capacitance) or whether it + is a static (steady-state) load step for the indicated DOFs. Transient initial conditions are + introduced at the load step having ``Key`` = ON. Initial conditions are then determined from the + previous two substeps. Zero initial velocity and acceleration are assumed if no previous substeps + exist. See the `Structural Analysis Guide + `_, the + `Thermal Analysis Guide + `_, and the `Low- + Frequency Electromagnetic Analysis Guide + `_ for details. This command is also valid in PREP7. """ @@ -1333,90 +1854,90 @@ def timint(self, key="", lab="", **kwargs): def tintp( self, - gamma="", - alpha="", - delta="", - theta="", - oslm="", - tol="", - avsmooth="", - alphaf="", - alpham="", + gamma: str = "", + alpha: str = "", + delta: str = "", + theta: str = "", + oslm: str = "", + tol: str = "", + avsmooth: int | str = "", + alphaf: str = "", + alpham: str = "", **kwargs, ): - """Defines transient integration parameters. + r"""Defines transient integration parameters. - APDL Command: TINTP + Mechanical APDL Command: `TINTP `_ Parameters ---------- - gamma - Amplitude decay factor for 2nd order transient integration, e.g., - structural dynamics (used only if ALPHA, DELTA, ALPHAF, and ALPHAM - are blank). Defaults to 0.005. + gamma : str + Amplitude decay factor for 2nd order transient integration, for example, structural dynamics (used + only if ``ALPHA``, ``DELTA``, ``ALPHAF``, and ``ALPHAM`` are blank). Defaults to 0.005. + + Alternatively, you can input the application type for the analysis using one of the following + labels. In this case, the program automatically sets the transient dynamic solver algorithm and + settings based on the intended application. For more information, see. + + * ``IMPA`` - Impact application. - alpha - 2nd order transient integration parameter (used only if GAMMA is - blank). Defaults to 0.2525. + * ``HISP`` - High speed dynamic application. - delta - 2nd order transient integration parameter (used only if GAMMA is - blank). Defaults to 0.5050. + * ``MOSP`` - Moderate speed dynamic application. - theta - 1st order transient (e.g., thermal transient) integration - parameter. Defaults to 1.0. + * ``LOSP`` - Low speed dynamic application. - oslm - Specifies the oscillation limit criterion for automatic time - stepping of 1st order transients (e.g., thermal transients). - Defaults to 0.5 with a tolerance of TOL. + * ``QUAS`` - Quasi-static application. - tol - Tolerance applied to OSLM. Defaults to 0.0. + alpha : str + 2nd order transient integration parameter (used only if ``GAMMA`` is blank). Defaults to 0.2525. - avsmooth + delta : str + 2nd order transient integration parameter (used only if ``GAMMA`` is blank). Defaults to 0.5050. + + theta : str + 1st order transient (for example, thermal transient) integration parameter. Defaults to 1.0 + + oslm : str + Specifies the oscillation limit criterion for automatic time stepping of 1st order transients + (for example, thermal transients). Defaults to 0.5 with a tolerance of ``TOL``. + + tol : str + Tolerance applied to ``OSLM``. Defaults to 0.0. + + avsmooth : int or str Smoothing flag option: - 0 - Include smoothing of the velocity (1st order system) - or the acceleration (2nd order system) (default). + * ``0`` - Include smoothing of the velocity (1st order system) or the acceleration (2nd order + system) (default). - 1 - Do not include smoothing. + * ``1`` - Do not include smoothing. - alphaf - Interpolation factor in HHT algorithm for force and damping terms - (used only if GAMMA is blank). Defaults to 0.005. + alphaf : str + Interpolation factor in HHT algorithm for force and damping terms (used only if ``GAMMA`` is + blank). Defaults to 0.005. - alpham - Interpolation factor in HHT algorithm for inertial term (used only - if GAMMA is blank). Defaults to 0.0. + alpham : str + Interpolation factor in HHT algorithm for inertial term (used only if ``GAMMA`` is blank). + Defaults to 0.0. Notes ----- - Used to define the transient integration parameters. For more - information on transient integration parameters, refer to the - Mechanical APDL Theory Reference. - - For structural transient analyses, you may choose between the - Newmark and HHT time integration methods (see the TRNOPT - command). In this case, if GAMMA is input and the integration - parameters ALPHA, DELTA, ALPHAF, and ALPHAM are left blank, - the program will calculate the integration - parameters. Alternatively, you can input these integration - parameters directly on this command. However, for the - unconditional stability and second order accuracy of the time - integration, these parameters should satisfy a specific - relationship, as described in Description of Structural and - Other Second Order Systems of the Mechanical APDL Theory - Reference. - - In a transient piezoelectric analysis, required input for this - command is ALPHA = 0.25, DELTA = 0.5, and THETA = 0.5. For a - coupled electromagnetic-circuit transient analysis, use THETA - = 1.0, the default value, to specify the backward Euler - method. + + .. _TINTP_notes: + + Used to define the transient integration parameters. For more information on transient integration + parameters, refer to `Transient Analysis + `_ + + For structural transient analyses, you may choose between the Newmark and HHT time integration + methods (see the :ref:`trnopt` command). In this case, if ``GAMMA`` is input and the integration + parameters ``ALPHA``, ``DELTA``, ``ALPHAF``, and ``ALPHAM`` are left blank, the program will + calculate the integration parameters. Alternatively, you can input these integration parameters + directly on this command. However, for the unconditional stability and second order accuracy of the + time integration, these parameters should satisfy a specific relationship, as described in + `Description of Structural and Other Second Order Systems + `_ This command is also valid in PREP7. """ @@ -1425,149 +1946,138 @@ def tintp( def trnopt( self, - method="", - maxmode="", - initialacc="", - minmode="", - mcfwrite="", - tintopt="", - vaout="", - dmpsfreq="", - engcalc="", - mckey="", + method: str = "", + maxmode: str = "", + initialacc: str = "", + minmode: str = "", + mcfwrite: str = "", + tintopt: str = "", + vaout: str = "", + dmpsfreq: str = "", + engcalc: str = "", + mckey: str = "", **kwargs, ): - """Specifies transient analysis options. + r"""Specifies transient analysis options. - APDL Command: TRNOPT + Mechanical APDL Command: `TRNOPT `_ Parameters ---------- - method + method : str Solution method for the transient analysis: - FULL - Full method (default). - - MSUP - Mode-superposition method. + * ``FULL`` - Full method (default). - VT - Variational Technology method. (Removed by V18.2) + * ``MSUP`` - Mode-superposition method. - maxmode - Largest mode number to be used to calculate the response - (for Method = MSUP). Defaults to the highest mode - calculated in the preceding modal analysis. + maxmode : str + Largest mode number to be used to calculate the response (for ``Method`` = MSUP). Defaults to + the highest mode calculated in the preceding modal analysis. - initialacc + initialacc : str Key to activate calculation of initial acceleration: - (blank) - Initial accelerations are not calculated (default). + * ``(blank)`` - Initial accelerations are not calculated (default). - INIL - Calculate initial acceleration for a full transient analysis - using the lumped mass matrix. + * ``INIL`` - Calculate initial acceleration for a full transient analysis using the lumped mass + matrix. - minmode - Smallest mode number to be used (for Method = MSUP). - Defaults to 1. + minmode : str + Smallest mode number to be used (for ``Method`` = MSUP). Defaults to 1. - mcfwrite - Modal coordinates output key to the .mcf file (valid only - for the mode-superposition method): + mcfwrite : str + Modal coordinates output key to the :file:`Jobname.mcf` file (valid only for the mode-superposition + method). To control how :file:`Jobname.mcf` is written, specify options on the :ref:`mcfopt` + command. - NO - No output of modal coordinates (default). + * ``NO`` - Modal coordinates are not written to :file:`Jobnamemcf`. - YES - Output modal coordinates to the text file Jobname.MCF. + * ``YES`` - Modal coordinates are written to the text file :file:`Jobname.mcf` (default). - tintopt - Time integration method for the transient analysis: + tintopt : str + `Time integration method + `_ for the + transient analysis: - NMK or 0 - Newmark algorithm (default). + * ``NMK or 0`` - Newmark algorithm (default). - HHT or 1 - HHT algorithm (valid only for the full transient method). + * ``HHT or 1`` - HHT algorithm (valid only for the full transient method). - vaout - Velocities and accelerations output key (valid only for - mode- superposition transient analysis): + vaout : str + Velocities and accelerations output key (valid only for `mode-superposition transient analysis + `_ + ): - NO - No output of velocities and accelerations (default). + * ``NO`` - No output of velocities and accelerations (default). - YES - Write velocities and accelerations on the reduced displacement - file Jobname.RDSP. + * ``YES`` - Write velocities and accelerations to the reduced displacement file, + :file:`Jobnamerdsp`. - dmpsfreq - Average excitation frequency (Hz) for the calculation of - equivalent viscous damping from structural damping input - (DMPSTR and MP,DMPS). See Damping for more - details. Defaults to zero. If an excitation frequency is - not specified, structural damping is ignored. If tabular - excitation frequency data is provided in a full transient - analysis (DMPSFreqTab on DMPSTR), it supersedes this - value. + dmpsfreq : str + Average excitation frequency (Hz) for the calculation of equivalent viscous damping from + structural damping input ( :ref:`dmpstr` and :ref:`mp`,DMPS). See `Damping + `_ + ``DMPSFreqTab`` on :ref:`dmpstr` ), it supersedes this value. - engcalc + engcalc : str Additional element energies calculation key: - NO - Do not calculate additional element energies - (default). + * ``NO`` - Do not calculate additional element energies (default). - YES - Calculate damping energy and work done by external - loads. + * ``YES`` - Calculate damping energy and work done by external loads. - mckey - Modal coordinates output key to the .rdsp file (valid only - for the mode-superposition method): + mckey : str + Modal coordinates output key to the :file:`.rdsp` file (valid only for the mode-superposition + method): - AUTO - Writing depends on the modal analysis settings of - the MXPAND command (default). + * ``AUTO`` - Writing depends on the modal analysis settings of the :ref:`mxpand` command (default). - YES - Always write the modal coordinates to the file - Jobname.rdsp. A subsequent expansion pass (EXPASS) is not - supported. + * ``YES`` - Always write the modal coordinates to the file :file:`Jobname.rdsp`. A subsequent + expansion pass ( :ref:`expass` ) is not supported. Notes ----- - Specifies transient analysis (ANTYPE,TRANS) options. If used - in SOLUTION, this command is valid only within the first load - step. Use the TINTP command to set transient integration + + .. _TRNOPT_notes: + + Specifies transient analysis ( :ref:`antype`,TRANS) options. If used in SOLUTION, this command is + valid only within the first load step. Use the :ref:`tintp` command to set transient integration parameters. - To include residual vectors in your mode-superposition - transient analysis (Method = MSUP), specify RESVEC,ON. + To include `residual vectors + `_ + in your `mode-superposition transient + `_ + analysis ( ``Method`` = MSUP), specify :ref:`resvec`,ON. - Method = MSUP is not available for ocean loading. + For ``Method`` = MSUP, ``MAXMODE`` and ``MINMODE`` are ignored after a modal restart analysis where + remote modal files usage ( :ref:`moddir` ) and residual vector calculation ( :ref:`resvec`,ON) have + been activated. - By default in a mode-superposition transient analysis, - reaction force and other force output contains only static - contributions. If you want to postprocess the velocities, - accelerations, and derived results (Lab = TOTAL, DAMP, or - INERT on the FORCE command), set VAout = YES to activate - velocity and acceleration output. + ``Method`` = MSUP is not available for ocean loading. - The calculation of additional energies (EngCalc = YES) is - valid only for the full solution method (Method = FULL). The - Jobname.ESAV file is always saved in this case. The numerical - integration for damping energy and work are consistent only if - solution data are written to the database for every substep - (OUTRES,ALL,ALL, OUTRES,ESOL,ALL, or OUTRES,VENG, ALL). For - more information, see Damping Energy and Work Done by External - Loads in the Mechanical APDL Theory Reference. + By default in a mode-superposition transient analysis, reaction force and other force output + contains only static contributions. If you want to postprocess the velocities, accelerations, and + derived results ( ``Lab`` = TOTAL, DAMP, or INERT on the :ref:`force` command), set ``VAout`` = YES + to activate velocity and acceleration output. + + The calculation of additional energies ( ``EngCalc`` = YES) is valid only for the full solution + method ( ``Method`` = FULL). The :file:`Jobname.ESAV` file is always saved in this case. The + numerical integration for damping energy and work are consistent only if solution data are written + to the database for every substep ( :ref:`outres`,ALL,ALL, :ref:`outres`,ESOL,ALL, or + :ref:`outres`,VENG, ALL). For more information, see `Damping Energy + `_ `Work Done by + External Loads `_ This command is also valid in PREP7. + + .. _TRNOPT_extranote1: + + Additional product restrictions for the :ref:`trnopt` command are shown in the table below. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. """ command = f"TRNOPT,{method},{maxmode},{initialacc},{minmode},{mcfwrite},{tintopt},{vaout},{dmpsfreq},{engcalc},{mckey}" return self.run(command, **kwargs) - # TRNOPT,Method,MAXMODE,InitialAcc,MINMODE,MCFwrite,TINTOPT,VAout, DMPSFreq, EngCalc, MCkey diff --git a/src/ansys/mapdl/core/commands.py b/src/ansys/mapdl/core/commands.py index f9c5e3e1426..a1c725de532 100644 --- a/src/ansys/mapdl/core/commands.py +++ b/src/ansys/mapdl/core/commands.py @@ -469,6 +469,11 @@ class SessionCommands( class SolutionCommands( + solution._gap_conditions.GapConditions, + solution._nonlinear_options.NonlinearOptions, + solution._status.Status, + solution.additive_manufacturing.AdditiveManufacturing, + solution.analysis_2d_to_3d.Analysis2DTo3D, solution.analysis_options.AnalysisOptions, solution.birth_and_death.BirthAndDeath, solution.dynamic_options.DynamicOptions,