diff --git a/doc/changelog.d/4265.added.md b/doc/changelog.d/4265.added.md new file mode 100644 index 00000000000..a3c04ef0834 --- /dev/null +++ b/doc/changelog.d/4265.added.md @@ -0,0 +1 @@ +\`\`solution\`\` - part 2 diff --git a/doc/source/mapdl_commands/solution/fe_body_loads.rst b/doc/source/mapdl_commands/solution/fe_body_loads.rst index 3e804ad6123..a0afcde5dc0 100644 --- a/doc/source/mapdl_commands/solution/fe_body_loads.rst +++ b/doc/source/mapdl_commands/solution/fe_body_loads.rst @@ -1,27 +1,30 @@ -.. _ref_fe_body_loads_commands_api: -************* -FE body loads -************* +.. _ref_fe_body_loads: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define body loads on the finite element model. +FeBodyLoads +=========== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.fe_body_loads + +.. autoclass:: ansys.mapdl.core._commands.solution.fe_body_loads.FeBodyLoads .. autosummary:: - :toctree: _autosummary/ - - Mapdl.bf - Mapdl.bfcum - Mapdl.bfdele - Mapdl.bfe - Mapdl.bfecum - Mapdl.bfedele - Mapdl.bfelist - Mapdl.bfescal - Mapdl.bflist - Mapdl.bfscale - Mapdl.bfunif - Mapdl.ldread - Mapdl.rimport - Mapdl.tunif + :template: base.rst + :toctree: _autosummary + + + FeBodyLoads.bf + FeBodyLoads.bfcum + FeBodyLoads.bfdele + FeBodyLoads.bfe + FeBodyLoads.bfecum + FeBodyLoads.bfedele + FeBodyLoads.bfelist + FeBodyLoads.bfescal + FeBodyLoads.bflist + FeBodyLoads.bfport + FeBodyLoads.bfscale + FeBodyLoads.bfunif + FeBodyLoads.tunif diff --git a/doc/source/mapdl_commands/solution/fe_constraints.rst b/doc/source/mapdl_commands/solution/fe_constraints.rst index fd7985f66ee..ee3945358fe 100644 --- a/doc/source/mapdl_commands/solution/fe_constraints.rst +++ b/doc/source/mapdl_commands/solution/fe_constraints.rst @@ -1,26 +1,31 @@ -.. _ref_fe_constraints_commands_api: -************** -FE constraints -************** +.. _ref_fe_constraints: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define constraints on the finite element model. +FeConstraints +============= + + +.. currentmodule:: ansys.mapdl.core._commands.solution.fe_constraints + +.. autoclass:: ansys.mapdl.core._commands.solution.fe_constraints.FeConstraints .. autosummary:: - :toctree: _autosummary/ - - Mapdl.d - Mapdl.dcum - Mapdl.ddele - Mapdl.dflx - Mapdl.dj - Mapdl.djdele - Mapdl.djlist - Mapdl.dlist - Mapdl.dscale - Mapdl.dsym - Mapdl.dval - Mapdl.gsbdata - Mapdl.gslist + :template: base.rst + :toctree: _autosummary + + + FeConstraints.d + FeConstraints.dcum + FeConstraints.ddele + FeConstraints.dflx + FeConstraints.dj + FeConstraints.djdele + FeConstraints.djlist + FeConstraints.dlist + FeConstraints.dscale + FeConstraints.dsym + FeConstraints.dval + FeConstraints.gsbdata + FeConstraints.gslist + FeConstraints.ldread diff --git a/doc/source/mapdl_commands/solution/fe_forces.rst b/doc/source/mapdl_commands/solution/fe_forces.rst index 3a1c5f4e157..af992a7a49e 100644 --- a/doc/source/mapdl_commands/solution/fe_forces.rst +++ b/doc/source/mapdl_commands/solution/fe_forces.rst @@ -1,22 +1,25 @@ -.. _ref_fe_forces_commands_api: -********* -FE forces -********* +.. _ref_fe_forces: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define nodal loads on the finite element model. +FeForces +======== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.fe_forces + +.. autoclass:: ansys.mapdl.core._commands.solution.fe_forces.FeForces .. autosummary:: - :toctree: _autosummary/ - - Mapdl.f - Mapdl.fcum - Mapdl.fdele - Mapdl.fj - Mapdl.fjdele - Mapdl.fjlist - Mapdl.flist - Mapdl.fscale - Mapdl.fssect + :template: base.rst + :toctree: _autosummary + + + FeForces.f + FeForces.fcum + FeForces.fdele + FeForces.fj + FeForces.fjdele + FeForces.fjlist + FeForces.flist + FeForces.fscale diff --git a/doc/source/mapdl_commands/solution/fe_surface_loads.rst b/doc/source/mapdl_commands/solution/fe_surface_loads.rst index d6d3d616ca8..109dbc9d926 100644 --- a/doc/source/mapdl_commands/solution/fe_surface_loads.rst +++ b/doc/source/mapdl_commands/solution/fe_surface_loads.rst @@ -1,24 +1,29 @@ -.. _ref_fe_surface_loads_commands_api: -**************** -FE surface loads -**************** +.. _ref_fe_surface_loads: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define surface loads on the finite element model. +FeSurfaceLoads +============== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.fe_surface_loads + +.. autoclass:: ansys.mapdl.core._commands.solution.fe_surface_loads.FeSurfaceLoads .. autosummary:: - :toctree: _autosummary/ - - Mapdl.sf - Mapdl.sfbeam - Mapdl.sfcum - Mapdl.sfdele - Mapdl.sfe - Mapdl.sfedele - Mapdl.sfelist - Mapdl.sffun - Mapdl.sfgrad - Mapdl.sflist - Mapdl.sfscale + :template: base.rst + :toctree: _autosummary + + + FeSurfaceLoads.sf + FeSurfaceLoads.sfbeam + FeSurfaceLoads.sfcontrol + FeSurfaceLoads.sfcum + FeSurfaceLoads.sfdele + FeSurfaceLoads.sfe + FeSurfaceLoads.sfedele + FeSurfaceLoads.sfelist + FeSurfaceLoads.sffun + FeSurfaceLoads.sfgrad + FeSurfaceLoads.sflist + FeSurfaceLoads.sfscale diff --git a/doc/source/mapdl_commands/solution/gap_conditions.rst b/doc/source/mapdl_commands/solution/gap_conditions.rst deleted file mode 100644 index 0f5fe97a0f3..00000000000 --- a/doc/source/mapdl_commands/solution/gap_conditions.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _ref_gap_conditions_commands_api: - -************** -Gap conditions -************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are used to define gaps for transient dynamic analyses. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.gp - Mapdl.gpdele - Mapdl.gplist diff --git a/doc/source/mapdl_commands/solution/index.rst b/doc/source/mapdl_commands/solution/index.rst index 105a02abf3e..0822fe4b068 100644 --- a/doc/source/mapdl_commands/solution/index.rst +++ b/doc/source/mapdl_commands/solution/index.rst @@ -7,13 +7,24 @@ Solution .. list-table:: * - :ref:`ref_analysis_options` + * - :ref:`ref_inertia` * - :ref:`ref_dynamic_options` * - :ref:`ref_additive_manufacturing` + * - :ref:`ref_misc_loads` + * - :ref:`ref_nonlinear_options` + * - :ref:`ref_load_step_options` + * - :ref:`ref_fe_body_loads` * - :ref:`ref__nonlinear_options` + * - :ref:`ref_fe_constraints` * - :ref:`ref_birth_and_death` + * - :ref:`ref_fe_forces` * - :ref:`ref__status` * - :ref:`ref__gap_conditions` + * - :ref:`ref_radiosity` + * - :ref:`ref_load_step_operations` + * - :ref:`ref_master_dof` * - :ref:`ref_analysis_2d_to_3d` + * - :ref:`ref_fe_surface_loads` .. toctree:: @@ -21,10 +32,20 @@ Solution :hidden: analysis_options + inertia dynamic_options additive_manufacturing + misc_loads + nonlinear_options + load_step_options + fe_body_loads _nonlinear_options + fe_constraints birth_and_death + fe_forces _status _gap_conditions + load_step_operations + master_dof analysis_2d_to_3d + fe_surface_loads diff --git a/doc/source/mapdl_commands/solution/inertia.rst b/doc/source/mapdl_commands/solution/inertia.rst index e11f32a699e..b7b3d65c1ff 100644 --- a/doc/source/mapdl_commands/solution/inertia.rst +++ b/doc/source/mapdl_commands/solution/inertia.rst @@ -1,26 +1,31 @@ -.. _ref_inertia_commands_api: -******* +.. _ref_inertia: + + Inertia -******* +======= + -.. currentmodule:: ansys.mapdl.core +.. currentmodule:: ansys.mapdl.core._commands.solution.inertia -These SOLUTION commands are used to define inertial loads on the model. +.. autoclass:: ansys.mapdl.core._commands.solution.inertia.Inertia .. autosummary:: - :toctree: _autosummary/ - - Mapdl.acel - Mapdl.cgloc - Mapdl.cgomga - Mapdl.cmacel - Mapdl.cmdomega - Mapdl.cmomega - Mapdl.cmrotate - Mapdl.coriolis - Mapdl.dcgomg - Mapdl.domega - Mapdl.irlf - Mapdl.omega - Mapdl.synchro + :template: base.rst + :toctree: _autosummary + + + Inertia.acel + Inertia.airl + Inertia.cgloc + Inertia.cgomga + Inertia.cmacel + Inertia.cmdomega + Inertia.cmomega + Inertia.cmrotate + Inertia.coriolis + Inertia.dcgomg + Inertia.domega + Inertia.irlf + Inertia.omega + Inertia.synchro diff --git a/doc/source/mapdl_commands/solution/load_step_operations.rst b/doc/source/mapdl_commands/solution/load_step_operations.rst index 6ab91ef760d..25bbca513dd 100644 --- a/doc/source/mapdl_commands/solution/load_step_operations.rst +++ b/doc/source/mapdl_commands/solution/load_step_operations.rst @@ -1,18 +1,22 @@ -.. _ref_load_step_operations_commands_api: -******************** -Load step operations -******************** +.. _ref_load_step_operations: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to write and solve multiple load steps. +LoadStepOperations +================== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.load_step_operations + +.. autoclass:: ansys.mapdl.core._commands.solution.load_step_operations.LoadStepOperations .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.lsclear - Mapdl.lsdele - Mapdl.lsread - Mapdl.lssolve - Mapdl.lswrite + LoadStepOperations.lsclear + LoadStepOperations.lsdele + LoadStepOperations.lsread + LoadStepOperations.lssolve + LoadStepOperations.lswrite diff --git a/doc/source/mapdl_commands/solution/load_step_options.rst b/doc/source/mapdl_commands/solution/load_step_options.rst index aa3552813d1..05e0b8eab55 100644 --- a/doc/source/mapdl_commands/solution/load_step_options.rst +++ b/doc/source/mapdl_commands/solution/load_step_options.rst @@ -1,31 +1,35 @@ -.. _ref_load_step_options_commands_api: -***************** -Load step options -***************** +.. _ref_load_step_options: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define options for individual load steps. +LoadStepOptions +=============== + + +.. currentmodule:: ansys.mapdl.core._commands.solution.load_step_options + +.. autoclass:: ansys.mapdl.core._commands.solution.load_step_options.LoadStepOptions .. autosummary:: - :toctree: _autosummary/ - - Mapdl.autots - Mapdl.campbell - Mapdl.cecmod - Mapdl.deltim - Mapdl.expsol - Mapdl.kbc - Mapdl.kuse - Mapdl.magopt - Mapdl.magsolv - Mapdl.mode - Mapdl.nsubst - Mapdl.numexp - Mapdl.time - Mapdl.tref - Mapdl.tsres - Mapdl.upcoord - Mapdl.usrcal - Mapdl.wrfull + :template: base.rst + :toctree: _autosummary + + + LoadStepOptions.autots + LoadStepOptions.campbell + LoadStepOptions.cecmod + LoadStepOptions.deltim + LoadStepOptions.expsol + LoadStepOptions.kbc + LoadStepOptions.kuse + LoadStepOptions.magopt + LoadStepOptions.magsolv + LoadStepOptions.mode + LoadStepOptions.nsubst + LoadStepOptions.numexp + LoadStepOptions.time + LoadStepOptions.tref + LoadStepOptions.tsres + LoadStepOptions.upcoord + LoadStepOptions.usrcal + LoadStepOptions.wrfull diff --git a/doc/source/mapdl_commands/solution/master_dof.rst b/doc/source/mapdl_commands/solution/master_dof.rst index ac6d36e893d..939f2a5c236 100644 --- a/doc/source/mapdl_commands/solution/master_dof.rst +++ b/doc/source/mapdl_commands/solution/master_dof.rst @@ -1,17 +1,21 @@ -.. _ref_master_dof_commands_api: -************************* -Master degrees of freedom -************************* +.. _ref_master_dof: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define master degrees of freedom. +MasterDof +========= + + +.. currentmodule:: ansys.mapdl.core._commands.solution.master_dof + +.. autoclass:: ansys.mapdl.core._commands.solution.master_dof.MasterDof .. autosummary:: - :toctree: _autosummary/ + :template: base.rst + :toctree: _autosummary + - Mapdl.m - Mapdl.mdele - Mapdl.mgen - Mapdl.mlist + MasterDof.m + MasterDof.mdele + MasterDof.mgen + MasterDof.mlist diff --git a/doc/source/mapdl_commands/solution/misc_loads.rst b/doc/source/mapdl_commands/solution/misc_loads.rst new file mode 100644 index 00000000000..7f463ae1025 --- /dev/null +++ b/doc/source/mapdl_commands/solution/misc_loads.rst @@ -0,0 +1,38 @@ + +.. _ref_misc_loads: + + +MiscLoads +========= + + +.. currentmodule:: ansys.mapdl.core._commands.solution.misc_loads + +.. autoclass:: ansys.mapdl.core._commands.solution.misc_loads.MiscLoads + +.. autosummary:: + :template: base.rst + :toctree: _autosummary + + + MiscLoads.anpres + MiscLoads.aport + MiscLoads.asifile + MiscLoads.awave + MiscLoads.biot + MiscLoads.dfswave + MiscLoads.fluread + MiscLoads.ic + MiscLoads.icdele + MiscLoads.iclist + MiscLoads.icrotate + MiscLoads.mrpm + MiscLoads.osresult + MiscLoads.outgeom + MiscLoads.outpr + MiscLoads.outres + MiscLoads.rescontrol + MiscLoads.rstcontrol + MiscLoads.sbclist + MiscLoads.sbctran + MiscLoads.wsprings diff --git a/doc/source/mapdl_commands/solution/miscellaneous_loads.rst b/doc/source/mapdl_commands/solution/miscellaneous_loads.rst deleted file mode 100644 index fa89f164732..00000000000 --- a/doc/source/mapdl_commands/solution/miscellaneous_loads.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _ref_miscellaneous_loads_commands_api: - -******************* -Miscellaneous loads -******************* - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are for miscellaneous load definition and control. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.anpres - Mapdl.aport - Mapdl.asifile - Mapdl.awave - Mapdl.biot - Mapdl.dfswave - Mapdl.fluread - Mapdl.ic - Mapdl.icdele - Mapdl.iclist - Mapdl.icrotate - Mapdl.mrpm - Mapdl.outpr - Mapdl.outres - Mapdl.rescontrol - Mapdl.sbclist - Mapdl.sbctran - Mapdl.wsprings diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_convergence_controls.rst b/doc/source/mapdl_commands/solution/multi_field_solver_convergence_controls.rst deleted file mode 100644 index 982aac376cf..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_convergence_controls.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _ref_multi_field_solver_convergence_controls_commands_api: - -*************************************** -Multi-Field solver convergence controls -*************************************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are used to define convergence controls for an -ANSYS Multi-field solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfconv - Mapdl.mfiter - Mapdl.mfrelax diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_definition_commands.rst b/doc/source/mapdl_commands/solution/multi_field_solver_definition_commands.rst deleted file mode 100644 index 205613efd6a..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_definition_commands.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ref_multi_field_solver_definition_commands_commands_api: - -************************************** -Multi-Field solver definition commands -************************************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are used to define the fields for an ANSYS -Multi-field solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfcmmand - Mapdl.mfelem - Mapdl.mfem - Mapdl.mfexter - Mapdl.mffname diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_global_controls.rst b/doc/source/mapdl_commands/solution/multi_field_solver_global_controls.rst deleted file mode 100644 index b01f2c4137a..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_global_controls.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _ref_multi_field_solver_global_controls_commands_api: - -********************************** -Multi-Field solver global controls -********************************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands set global controls for an ANSYS Multi-field -solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfanalysis - Mapdl.mfclear - Mapdl.mffr - Mapdl.mfinter - Mapdl.mflist - Mapdl.mforder - Mapdl.mfpsimul - Mapdl.mfsorder - Mapdl.mfwrite diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_interface_mapping.rst b/doc/source/mapdl_commands/solution/multi_field_solver_interface_mapping.rst deleted file mode 100644 index db866cd137f..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_interface_mapping.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _ref_multi_field_solver_interface_mapping_commands_api: - -************************************ -Multi-Field solver interface mapping -************************************ - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are used to define mapping details for an -ANSYS Multi-field solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfbucket - Mapdl.mfci - Mapdl.mfmap - Mapdl.mftol diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_load_transfer.rst b/doc/source/mapdl_commands/solution/multi_field_solver_load_transfer.rst deleted file mode 100644 index 3189e830b93..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_load_transfer.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _ref_multi_field_solver_load_transfer_commands_api: - -******************************** -Multi-Field solver load transfer -******************************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands are used to define load transfer for an ANSYS -Multi-field solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mflcomm - Mapdl.mfsurface - Mapdl.mfvolume diff --git a/doc/source/mapdl_commands/solution/multi_field_solver_time_controls.rst b/doc/source/mapdl_commands/solution/multi_field_solver_time_controls.rst deleted file mode 100644 index 33884795314..00000000000 --- a/doc/source/mapdl_commands/solution/multi_field_solver_time_controls.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _ref_multi_field_solver_time_controls_commands_api: - -******************************** -Multi-Field solver time controls -******************************** - -.. currentmodule:: ansys.mapdl.core - -These SOLUTION commands set time controls for an ANSYS Multi-field -solver analysis. - -.. autosummary:: - :toctree: _autosummary/ - - Mapdl.mfcalc - Mapdl.mfdtime - Mapdl.mfoutput - Mapdl.mfrstart - Mapdl.mftime diff --git a/doc/source/mapdl_commands/solution/nonlinear_options.rst b/doc/source/mapdl_commands/solution/nonlinear_options.rst index 43cebbafcb8..a6a2719579d 100644 --- a/doc/source/mapdl_commands/solution/nonlinear_options.rst +++ b/doc/source/mapdl_commands/solution/nonlinear_options.rst @@ -1,30 +1,37 @@ -.. _ref_nonlinear_options_commands_api: -***************** -Nonlinear options -***************** +.. _ref_nonlinear_options: -.. currentmodule:: ansys.mapdl.core -These SOLUTION commands are used to define options for nonlinear analyses. +NonlinearOptions +================ + + +.. currentmodule:: ansys.mapdl.core._commands.solution.nonlinear_options + +.. autoclass:: ansys.mapdl.core._commands.solution.nonlinear_options.NonlinearOptions .. autosummary:: - :toctree: _autosummary/ - - Mapdl.arclen - Mapdl.arctrm - Mapdl.bucopt - Mapdl.cnvtol - Mapdl.crplim - Mapdl.gst - Mapdl.lnsrch - Mapdl.ncnv - Mapdl.neqit - Mapdl.nladaptive - Mapdl.nldiag - Mapdl.nlgeom - Mapdl.nlhist - Mapdl.nlmesh - Mapdl.nropt - Mapdl.pred - Mapdl.pstres + :template: base.rst + :toctree: _autosummary + + + NonlinearOptions.arclen + NonlinearOptions.arctrm + NonlinearOptions.bucopt + NonlinearOptions.cnvtol + NonlinearOptions.gst + NonlinearOptions.lnsrch + NonlinearOptions.ncnv + NonlinearOptions.neqit + NonlinearOptions.nladaptive + NonlinearOptions.nldiag + NonlinearOptions.nlgeom + NonlinearOptions.nlhist + NonlinearOptions.nlmesh + NonlinearOptions.nropt + NonlinearOptions.pred + NonlinearOptions.pstres + NonlinearOptions.semiimplicit + NonlinearOptions.soloption + NonlinearOptions.ssopt + NonlinearOptions.sstif diff --git a/src/ansys/mapdl/core/_commands/solution/__init__.py b/src/ansys/mapdl/core/_commands/solution/__init__.py index 50193b80dfc..659d890f2ad 100644 --- a/src/ansys/mapdl/core/_commands/solution/__init__.py +++ b/src/ansys/mapdl/core/_commands/solution/__init__.py @@ -33,18 +33,11 @@ fe_constraints, fe_forces, fe_surface_loads, - gap_conditions, inertia, load_step_operations, load_step_options, master_dof, - miscellaneous_loads, - multi_field_solver_convergence_controls, - multi_field_solver_definition_commands, - multi_field_solver_global_controls, - multi_field_solver_interface_mapping, - multi_field_solver_load_transfer, - multi_field_solver_time_controls, + misc_loads, nonlinear_options, ocean, radiosity, diff --git a/src/ansys/mapdl/core/_commands/solution/fe_body_loads.py b/src/ansys/mapdl/core/_commands/solution/fe_body_loads.py index a5db23013f2..70c7928dcb6 100644 --- a/src/ansys/mapdl/core/_commands/solution/fe_body_loads.py +++ b/src/ansys/mapdl/core/_commands/solution/fe_body_loads.py @@ -22,170 +22,1198 @@ class FeBodyLoads: + def bf( self, - node="", - lab="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", + node: str = "", + lab: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + meshflag: str = "", **kwargs, ): - """Defines a nodal body force load. + r"""Defines a nodal body-force load. + + Mechanical APDL Command: `BF `_ + + Parameters + ---------- + node : str + Node to which body load applies. If ``Node`` = ALL, apply to all selected nodes ( :ref:`nsel` ). + A component name may also be substituted for ``Node``. + + lab : str + Valid body load label. Load labels are listed under Body Loads in the input table for each + element type in the `Element Reference + `_. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + val1 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = IMPD: + + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` + + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + val2 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = IMPD: + + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` + + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + val3 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = IMPD: + + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` + + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + val4 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = IMPD: + + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` + + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used - APDL Command: BF + * ``VAL6`` - Not used - Parameters - ---------- - node - Node to which body load applies. If Node = ALL, apply to all - selected nodes [NSEL]. A component name may also be substituted - for Node. + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + val5 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = IMPD: + + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` + + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + val6 : str + Value associated with the ``Lab`` item or table name reference for tabular boundary conditions. Use + only ``VAL1`` for TEMP, FLUE, HGEN, DGEN, MVDI, CHRGD, PORT, and SPRE. + + Tabular input is supported for certain labels (see :ref:`Notes for details). To specify a table, + enclose the table name in percent signs (%) (e.g., ` :ref:`bf`, + ``Node``,TEMP,``tabname``). Use the :ref:`dim` command to define a table. + + If ``Lab`` = MASS for acoustics: + + * ``VAL1`` - Mass source with units of kg/(m :sup:`3` *s) in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or mass source rate with units of kg/(m + :sup:`3` *s :sup:`2` ) in a transient analysis solved with the pressure formulation; or power source + with units of watts in an energy diffusion solution for room acoustics + + * ``VAL2`` - Phase angle in degrees + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for acoustics (velocity components in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; or acceleration components in a transient + analysis solved with the pressure formulation): + + * ``VAL1`` - X component + + * ``VAL2`` - Y component + + * ``VAL3`` - Z component + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = VELO for electromagnetics (velocity and angular velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Velocity component in the X direction + + * ``VAL2`` - Velocity component in the Y direction + + * ``VAL3`` - Velocity component in the Z direction + + * ``VAL4`` - Angular velocity about the X axis (rad/sec) + + * ``VAL5`` - Angular velocity about the Y axis (rad/sec) + + * ``VAL6`` - Angular velocity about the Z axis (rad/sec) + + If ``Lab`` = VELO for thermal (velocity components in the global Cartesian coordinate system): + + * ``VAL1`` - Mass transport velocity component in X direction + + * ``VAL2`` - Mass transport velocity component in Y direction + + * ``VAL3`` - Mass transport velocity component in Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VELO for diffusion (transport velocity): + + * ``VAL1`` - Transport velocity component in X direction + + * ``VAL2`` - Transport velocity component in Y direction + + * ``VAL3`` - Transport velocity component in Z direction - lab - Valid body load label. Load labels are listed under "Body Loads" in - the input table for each element type in the Element Reference. + * ``VAL4`` - Not used - val1, val2, val3, val4, val5, val6 - Value associated with the Lab item or table name reference for - tabular boundary conditions. To specify a table, enclose the table - name in percent signs (%) (e.g., BF,Node,TEMP,%tabname%). Use the - ``*DIM`` command to define a table. Use only VAL1 for TEMP, FLUE, HGEN, - DGEN, MVDI, CHRGD. If Lab = CHRGD for acoustics, VAL1 is the static - pressure for a non-uniform acoustic medium calculation. + * ``VAL5`` - Not used - VAL1 - Mass source with units kg/(m3s) in a harmonic analysis, or mass source rate - with units kg/( m3s2) in a transient analysis + * ``VAL6`` - Not used - VAL2 - Phase angle in degrees + If ``Lab`` = IMPD: - VAL3 - Not used + * ``VAL1`` - Resistance in N⋅s/m :sup:`3` - VAL4 - Not used + * ``VAL2`` - Reactance in N⋅s/m :sup:`3` - VAL5 - Not used + * ``VAL3`` - Not used - VAL6 - Not used + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = FPBC: + + * ``VAL1`` - Phase shift (product of phase constant and period in unit radian); or Floquet boundary + flag (set ``VAL1`` = YES) for a modal analysis that solves the eigenvalues with a specified + frequency ( ``FREQMOD`` on the :ref:`modopt` command) + + * ``VAL2`` - Attenuation (product of attenuation constant and period); not used if ``VAL1`` = YES + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = VMEN: + + * ``VAL1`` - Mean flow velocity component in the X direction + + * ``VAL2`` - Mean flow velocity component in the Y direction + + * ``VAL3`` - Mean flow velocity component in the Z direction + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = UFOR: + + * ``VAL1`` - Real part of complex force potential + + * ``VAL2`` - Imaginary part of complex force potential + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + If ``Lab`` = SFOR: + + * ``VAL1`` - X component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL2`` - Y component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL3`` - Z component of shear force for viscous-thermal acoustics or poroelastic acoustics + + * ``VAL4`` - X-component phase angle in degrees + + * ``VAL5`` - Y-component phase angle in degrees + + * ``VAL6`` - Z-component phase angle in degrees + + If ``Lab`` = HFLW: + + * ``VAL1`` - Real part of volumetric heat source for viscous-thermal acoustics + + * ``VAL2`` - Imaginary part of volumetric heat source for viscous-thermal acoustics + + * ``VAL3`` - Not used + + * ``VAL4`` - Not used + + * ``VAL5`` - Not used + + * ``VAL6`` - Not used + + meshflag : str + Specifies how to apply nodal body-force loading on the mesh. Valid in a `nonlinear adaptivity + analysis `_ when + ``Lab`` = HGEN or TEMP, and ``Node`` is not a component name. + + * 0 - Nodal body-force loading occurs on the current mesh (default). + * 1 - Nodal body-force loading occurs on the initial mesh for nonlinear adaptivity. Notes ----- - Defines a nodal body force load (such as temperature in a structural - analysis, heat generation rate in a thermal analysis, etc.). Nodal body - loads default to the BFUNIF values, if they were previously specified. - Table names are valid for Lab value (VALn) inputs in these cases only: + .. _BF_notes: + + Defines a nodal body-force load (such as temperature in a structural analysis, heat generation rate + in a thermal analysis, etc.). Nodal body loads default to the :ref:`bfunif` values, if they were + previously specified. - VAL = %tabname% for temperatures (TEMP), diffusing substance generation - rates (DGEN), heat generation rates (HGEN), and nodal body force - densities (FORC). + Table names are valid for ``Lab`` value ( ``VALn`` ) inputs in these cases only: - VAL1 = %tabname1%, VAL2 = %tabname2%, VAL3 = %tabname3%, VAL4 = - %tabname4%, VAL5 = %tabname5%, and VAL6 = %tabname6% for velocities or - accelerations (VELO). + * ``VAL1`` = ``tabname`` for: - VAL1 = %tabname1% and VAL2 = %tabname2% for mass sources or mass source - rates (MASS). + temperatures (TEMP), diffusing substance generation rates (DGEN), and heat generation rates (HGEN). - The heat generation rate loads specified with the BF command are - multiplied by the weighted nodal volume of each element adjacent to - that node. This yields the total heat generation at that node. + * ``VAL1`` = ``tabname1`` and ``VAL2`` = ``tabname2`` for: - Graphical picking is available only via the listed menu paths. + mass source, mass source rate, or power source (MASS); the Floquet periodic boundary condition + (FPBC); the force potential (UFOR); and the volumetric heat source (HFLW). - Body load labels VELO and MASS cannot be accessed from a menu. + * ``VAL1`` = ``tabname1``, ``VAL2`` = ``tabname2``, and ``VAL3`` = ``tabname3`` for: + + mean flow velocities (VMEN). + + * ``VAL1`` = ``tabname1``, ``VAL2`` = ``tabname2``, ``VAL3`` = ``tabname3``, ``VAL4`` = + ``tabname4``, ``VAL5`` = ``tabname5``, and ``VAL6`` = ``tabname6`` for: + + velocities or accelerations (VELO); and shear force (SFOR). + + The heat generation rate loads specified with the :ref:`bf` command are multiplied by the weighted + nodal volume of each element adjacent to that node. This yields the total heat generation at that + node. + + In a modal analysis, the Floquet periodic boundary condition (FPBC) is only valid for the acoustic + elements ``FLUID30``, ``FLUID220``, and ``FLUID221``. + + 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. This command is also valid in PREP7. """ - command = f"BF,{node},{lab},{val1},{val2},{val3},{val4},{val5},{val6}" + command = ( + f"BF,{node},{lab},{val1},{val2},{val3},{val4},{val5},{val6},{meshflag}" + ) return self.run(command, **kwargs) - def bfcum(self, lab="", oper="", fact="", tbase="", **kwargs): - """Specifies that nodal body force loads are to be accumulated. + def bfcum( + self, lab: str = "", oper: str = "", fact: str = "", tbase: str = "", **kwargs + ): + r"""Specifies that nodal body-force loads are to be accumulated. + + Mechanical APDL Command: `BFCUM `_ - APDL Command: BFCUM + **Command default:** + + .. _BFCUM_default: + + Replace previous values. Parameters ---------- - lab - Valid body load label. If ALL, use all appropriate labels. + lab : str + Valid body load label. If ALL, use all appropriate labels. - oper + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + oper : str Accumulation key: - REPL - Subsequent values replace the previous values (default). + * ``REPL`` - Subsequent values replace the previous values (default). + + * ``ADD`` - Subsequent values are added to the previous values. - ADD - Subsequent values are added to the previous values. + * ``IGNO`` - Subsequent values are ignored. - IGNO - Subsequent values are ignored. + fact : str + Scale factor for the nodal body load values. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. The scale factor is not applied to body load phase angles. - fact - Scale factor for the nodal body load values. Zero (or blank) - defaults to 1.0. Use a small number for a zero scale factor. The - scale factor is not applied to body load phase angles. + tbase : str + Used (only with ``Lab`` = TEMP) to calculate the temperature used in the add or replace operation + (see ``Oper`` ) as: - tbase - Used (only with Lab = TEMP) to calculate the temperature used in - the add or replace operation (see Oper) as: + Temperature = ``TBASE`` + ``FACT`` \* ( ``T`` - ``TBASE`` ) + + where ``T`` is the temperature specified on subsequent :ref:`bf` commands. ``TBASE`` defaults to + zero. Notes ----- - Allows repeated nodal body force loads to be replaced, added, or - ignored. Nodal body loads are applied with the BF command. Issue the - BFLIST command to list the nodal body loads. The operations occur when - the next body loads are defined. For example, issuing the BF command - with a temperature of 250 after a previous BF command with a - temperature of 200 causes the new value of the temperature to be 450 - with the add operation, 250 with the replace operation, or 200 with the - ignore operation. A scale factor is also available to multiply the - next value before the add or replace operation. A scale factor of 2.0 - with the previous "add" example results in a temperature of 700. The - scale factor is applied even if no previous values exist. Issue - BFCUM,STAT to show the current label, operation, and scale factors. - Solid model boundary conditions are not affected by this command, but - boundary conditions on the FE model are affected. - - Note:: : FE boundary conditions may still be overwritten by existing - solid model boundary conditions if a subsequent boundary condition - transfer occurs. - - BFCUM does not work for tabular boundary conditions. + + .. _BFCUM_notes: + + Allows repeated nodal body-force loads to be replaced, added, or ignored. Nodal body loads are + applied with the :ref:`bf` command. Issue the :ref:`bflist` command to list the nodal body loads. + The operations occur when the next body loads are defined. For example, issuing the :ref:`bf` + command with a temperature of 250 after a previous :ref:`bf` command with a temperature of 200 + causes the new value of the temperature to be 450 with the add operation, 250 with the replace + operation, or 200 with the ignore operation. A scale factor is also available to multiply the next + value before the add or replace operation. A scale factor of 2.0 with the previous "add" example + results in a temperature of 700. The scale factor is applied even if no previous values exist. Issue + :ref:`bfcum`,STAT to show the current label, operation, and scale factors. Solid model boundary + conditions are not affected by this command, but boundary conditions on the FE model are affected. + FE boundary conditions may still be overwritten by existing solid model boundary conditions if a + subsequent boundary condition transfer occurs. + + :ref:`bfcum` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"BFCUM,{lab},{oper},{fact},{tbase}" return self.run(command, **kwargs) - def bfdele(self, node="", lab="", **kwargs): - """Deletes nodal body force loads. + def bfdele(self, node: str = "", lab: str = "", **kwargs): + r"""Deletes nodal body-force loads. - APDL Command: BFDELE + Mechanical APDL Command: `BFDELE `_ Parameters ---------- - node - Node at which body load is to be deleted. If ALL, delete for all - selected nodes [NSEL]. If NODE = P, graphical picking is enabled - and all remaining command fields are ignored (valid only in the - GUI). A component name may also be substituted for NODE. + node : str + Node at which body load is to be deleted. If ALL, delete for all selected nodes ( :ref:`nsel` ). + If ``Node`` = P, graphical picking is enabled and all remaining command fields are ignored + (valid only in the GUI). You can substitute a component name for ``Node``. - lab - Valid body load label. If ALL, use all appropriate labels. See the - BF command for labels. In an explicit dynamic analysis, the only - valid body load label is TEMP. + lab : str + Valid body load label. If ALL, use all appropriate labels. See :ref:`bf`. Notes ----- - Deletes nodal body force loads for a specified node and label. Nodal - body loads may be defined with the BF command (except in an explicit - dynamic analysis). - The command BFDELE,TEMP can be used in an explicit dynamic analysis to - delete temperature loads that are read in by the LDREAD command. BFDELE - cannot be used to delete temperature loads defined by the EDLOAD - command (use EDLOAD,DELE to delete this type of load). + .. _BFDELE_notes: + + Deletes nodal body-force loads for a specified node and label. Nodal body loads are defined via + :ref:`bf`. This command is also valid in PREP7. """ @@ -194,659 +1222,631 @@ def bfdele(self, node="", lab="", **kwargs): def bfe( self, - elem="", - lab="", - stloc="", - val1="", - val2="", - val3="", - val4="", + elem: str = "", + lab: str = "", + stloc: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", **kwargs, ): - """Defines an element body force load. + r"""Defines an element body-force load. - APDL Command: BFE + Mechanical APDL Command: `BFE `_ Parameters ---------- - elem - The element to which body load applies. If ALL, apply to all - selected elements (ESEL). A component name may also be substituted - for Elem. - - lab - Valid body load label. Valid labels are also listed for each - element type in the Element Reference under "Body Loads" in the - input table. - - stloc - Starting location for entering VAL data, below. For example, if - STLOC = 1, data input in the VAL1 field applies to the first - element body load item available for the element type, VAL2 applies - to the second element item, etc. If STLOC = 5, data input in the - VAL1 field applies to the fifth element item, etc. Defaults to 1. - - val1, val2, val3, val4 - For Lab = TEMP, FLUE, DGEN, HGEN, and CHRGD, VAL1--VAL4 represent - body load values at the starting location and subsequent locations - (usually nodes) in the element. VAL1 can also represent a table - name for use with tabular boundary conditions. Enter only VAL1 for - a uniform body load across the element. For nonuniform loads, the - values must be input in the same order as shown in the input table - for the element type. Values initially default to the BFUNIF value - (except for CHRGD which defaults to zero). For subsequent - specifications, a blank leaves a previously specified value - unchanged; if the value was not previously specified, the default - value as described in the Element Reference is used. + elem : str + The element to which body load applies. If ALL, apply to all selected elements ( :ref:`esel` ). + A component name may also be substituted for ``Elem``. + + lab : str + Valid body load label. Valid labels are also listed for each element type in the `Element + Reference `_ + under "Body Loads" in the input table. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + stloc : str + Starting location for entering ``VAL`` data, below. For example, if ``STLOC`` = 1, data input in + the ``VAL1`` field applies to the first element body load item available for the element type, + ``VAL2`` applies to the second element item, etc. If ``STLOC`` = 5, data input in the ``VAL1`` + field applies to the fifth element item, etc. Defaults to 1. + + val1 : str + For ``Lab`` = TEMP, FLUE, DGEN, HGEN, and CHRGD, ``VAL1`` -- ``VAL4`` represent body load values + at the starting location and subsequent locations (usually nodes) in the element. ``VAL1`` can + also represent a table name for use with tabular boundary conditions. Enter only ``VAL1`` for a + uniform body load across the element. For nonuniform loads, the values must be input in the same + order as shown in the input table for the element type. Values initially default to the + :ref:`bfunif` value (except for CHRGD which defaults to zero). For subsequent specifications, a + blank leaves a previously specified value unchanged; if the value was not previously specified, + the default value as described in the `Element Reference + `_ is used. + + For ``Lab`` = JS and ``STLOC`` = 1, ``VAL1``, ``VAL2`` and ``VAL3`` are the X, Y, and Z + components of current density (in the element coordinate system), and ``VAL4`` is the phase + angle. + + For ``Lab`` = EF and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the X, Y, and Z + components of electric field (in the global Cartesian coordinate system). + + If ``Lab`` = FVIN in a unidirectional Mechanical APDL to Ansys CFX analysis, ``VAL2`` is the + volume interface number (not available from within the GUI), and ``VAL1``, ``VAL3``, and + ``VAL4`` are not used. + + For ``Lab`` = FORC and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the real X, Y, and Z + components of force density (in the global Cartesian coordinate system). + + For analyses that allow complex input, if ``Lab`` = FORC and ``STLOC`` = 4, ``VAL1``, ``VAL2``, + and ``VAL3`` are the imaginary X, Y, and Z components of force density (in the global Cartesian + coordinate system). + + val2 : str + For ``Lab`` = TEMP, FLUE, DGEN, HGEN, and CHRGD, ``VAL1`` -- ``VAL4`` represent body load values + at the starting location and subsequent locations (usually nodes) in the element. ``VAL1`` can + also represent a table name for use with tabular boundary conditions. Enter only ``VAL1`` for a + uniform body load across the element. For nonuniform loads, the values must be input in the same + order as shown in the input table for the element type. Values initially default to the + :ref:`bfunif` value (except for CHRGD which defaults to zero). For subsequent specifications, a + blank leaves a previously specified value unchanged; if the value was not previously specified, + the default value as described in the `Element Reference + `_ is used. + + For ``Lab`` = JS and ``STLOC`` = 1, ``VAL1``, ``VAL2`` and ``VAL3`` are the X, Y, and Z + components of current density (in the element coordinate system), and ``VAL4`` is the phase + angle. + + For ``Lab`` = EF and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the X, Y, and Z + components of electric field (in the global Cartesian coordinate system). + + If ``Lab`` = FVIN in a unidirectional Mechanical APDL to Ansys CFX analysis, ``VAL2`` is the + volume interface number (not available from within the GUI), and ``VAL1``, ``VAL3``, and + ``VAL4`` are not used. + + For ``Lab`` = FORC and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the real X, Y, and Z + components of force density (in the global Cartesian coordinate system). + + For analyses that allow complex input, if ``Lab`` = FORC and ``STLOC`` = 4, ``VAL1``, ``VAL2``, + and ``VAL3`` are the imaginary X, Y, and Z components of force density (in the global Cartesian + coordinate system). + + val3 : str + For ``Lab`` = TEMP, FLUE, DGEN, HGEN, and CHRGD, ``VAL1`` -- ``VAL4`` represent body load values + at the starting location and subsequent locations (usually nodes) in the element. ``VAL1`` can + also represent a table name for use with tabular boundary conditions. Enter only ``VAL1`` for a + uniform body load across the element. For nonuniform loads, the values must be input in the same + order as shown in the input table for the element type. Values initially default to the + :ref:`bfunif` value (except for CHRGD which defaults to zero). For subsequent specifications, a + blank leaves a previously specified value unchanged; if the value was not previously specified, + the default value as described in the `Element Reference + `_ is used. + + For ``Lab`` = JS and ``STLOC`` = 1, ``VAL1``, ``VAL2`` and ``VAL3`` are the X, Y, and Z + components of current density (in the element coordinate system), and ``VAL4`` is the phase + angle. + + For ``Lab`` = EF and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the X, Y, and Z + components of electric field (in the global Cartesian coordinate system). + + If ``Lab`` = FVIN in a unidirectional Mechanical APDL to Ansys CFX analysis, ``VAL2`` is the + volume interface number (not available from within the GUI), and ``VAL1``, ``VAL3``, and + ``VAL4`` are not used. + + For ``Lab`` = FORC and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the real X, Y, and Z + components of force density (in the global Cartesian coordinate system). + + For analyses that allow complex input, if ``Lab`` = FORC and ``STLOC`` = 4, ``VAL1``, ``VAL2``, + and ``VAL3`` are the imaginary X, Y, and Z components of force density (in the global Cartesian + coordinate system). + + val4 : str + For ``Lab`` = TEMP, FLUE, DGEN, HGEN, and CHRGD, ``VAL1`` -- ``VAL4`` represent body load values + at the starting location and subsequent locations (usually nodes) in the element. ``VAL1`` can + also represent a table name for use with tabular boundary conditions. Enter only ``VAL1`` for a + uniform body load across the element. For nonuniform loads, the values must be input in the same + order as shown in the input table for the element type. Values initially default to the + :ref:`bfunif` value (except for CHRGD which defaults to zero). For subsequent specifications, a + blank leaves a previously specified value unchanged; if the value was not previously specified, + the default value as described in the `Element Reference + `_ is used. + + For ``Lab`` = JS and ``STLOC`` = 1, ``VAL1``, ``VAL2`` and ``VAL3`` are the X, Y, and Z + components of current density (in the element coordinate system), and ``VAL4`` is the phase + angle. + + For ``Lab`` = EF and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the X, Y, and Z + components of electric field (in the global Cartesian coordinate system). + + If ``Lab`` = FVIN in a unidirectional Mechanical APDL to Ansys CFX analysis, ``VAL2`` is the + volume interface number (not available from within the GUI), and ``VAL1``, ``VAL3``, and + ``VAL4`` are not used. + + For ``Lab`` = FORC and ``STLOC`` = 1, ``VAL1``, ``VAL2``, and ``VAL3`` are the real X, Y, and Z + components of force density (in the global Cartesian coordinate system). + + For analyses that allow complex input, if ``Lab`` = FORC and ``STLOC`` = 4, ``VAL1``, ``VAL2``, + and ``VAL3`` are the imaginary X, Y, and Z components of force density (in the global Cartesian + coordinate system). Notes ----- - Defines an element body force load (such as temperature in a structural - analysis, heat generation rate in a thermal analysis, etc.). Body loads - and element specific defaults are described for each element type in - the Element Reference. If both the BF and BFE commands are used to - apply a body load to an element, the BFE command takes precedence. - For heat-generation (HGEN) loading on layered thermal solid elements - SOLID278 / SOLID279 (KEYOPT(3) = 1 or 2), or layered thermal shell - elements SHELL131 / SHELL132 (KEYOPT(3) = 1), STLOC refers to the layer - number (not the node). In such cases, use VAL1 through VAL4 to specify - the heat-generation values for the appropriate layers. Heat generation - is constant over the layer. + .. _BFE_notes: + + Defines an element body-force load (such as the temperature in a structural analysis or the heat- + generation rate in a thermal analysis). Body loads and element specific defaults are described for + each element type in the `Element Reference + `_. If both the + :ref:`bf` and :ref:`bfe` commands are used to apply a + body-force load to an element, the :ref:`bfe` command takes precedence. + + Imaginary values for FORC loading via :ref:`bfe` is supported by current-technology solid elements ( + ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, ``SOLID187``, and ``SOLID285`` ) and + reinforcing elements ( ``REINF263``, ``REINF264``, and ``REINF265`` ). Use only for modal or + harmonic analyses. Large-deflection effects must be disabled ( :ref:`nlgeom`,OFF). + + The following topics for applying HGEN loading via the :ref:`bfe` command are available: + + For HGEN loading on layered thermal solid elements ``SOLID278`` / ``SOLID279`` (KEYOPT(3) = 1 or 2), + or layered thermal shell elements ``SHELL131`` / ``SHELL132`` (KEYOPT(3) = 1), ``STLOC`` refers to + the layer number (not the node). In such cases, specify ``VAL1`` through ``VAL4`` to specify the + heat-generation values for the appropriate layers. Heat generation is constant over the layer. + + For HGEN loading on `reinforcing + `_ + elements ``REINF263``, ``REINF264``, and ``REINF265``, ``STLOC`` refers to the corner locations of + the reinforcing members (individual reinforcings): + + * ``REINF263`` and ``REINF264`` : Specify ``VAL1`` and ``VAL2`` for each member. For tables, specify + ``VAL1`` only. + + * ``REINF265`` : Specify ``VAL1``, ``VAL2``, ``VAL3``, and ``VAL4`` for each member. For tables, + specify ``VAL1`` only. - Specifying a Table + For FORC loading on reinforcing elements, ``STLOC`` refers to real ( ``STLOC`` = 1) or imaginary ( + ``STLOC`` = 4) components. - You can specify a table name (VAL1) when using temperature (TEMP), - diffusing substance generation rate (DGEN), heat generation rate - (HGEN), and current density (JS) body load labels. + When using the `standard method + `_ for + defining reinforcing, this is the only way to apply a body load (HGEN or FORC) on the reinforcing + members created after generating the REINF ``nnn`` reinforcing elements ( :ref:`ereinf` ). If + applying FORC loading, Mechanical APDL applies a uniform load to all reinforcing members if there + are + multiple members in selected elements. - Enclose the table name (tabname) in percent signs (%), as shown: + When using the `mesh-independent method + `_ for + defining reinforcing, you can apply a body load on the reinforcing members in the same way. The + preferred method, however, is to apply loads on the ``MESH200`` elements (via :ref:`bfe` or + :ref:`bf` for HGEN, BFE for FORC) before generating the REINF ``nnn`` reinforcing elements ( + :ref:`ereinf` ). Mechanical APDL maps the loads from the ``MESH200`` elements to the newly generated + REINF + ``nnn`` reinforcing elements automatically. If you need to apply the loads after generating the + reinforcing elements, apply them to ``MESH200`` elements and issue :ref:`bfport` to transfer the + loads to the reinforcing members. - BFE,Elem, Lab,STLOC,%tabname% + You can specify a table name ( ``VAL1`` ) when using temperature (TEMP), diffusing substance + generation rate (DGEN), heat generation rate (HGEN), and current density (JS) body load labels. - Use the ``*DIM`` command to define a table. + For the body-force-density label (FORC), you can specify a table for any of the ``VAL1`` through + ``VAL3`` arguments. Both 1D and 2D tables are valid; however, only 1D tables are valid in mode- + superposition harmonic and mode-superposition transient analyses. - For Lab = TEMP, each table defines NTEMP temperatures, as follows: + Enclose the table name ( ``tabname`` ) in percent signs (%), for example : - For layered elements, NTEMP is the number of layer interface corners - that allow temperature input. + :ref:`bfe`, ``Elem``, ``Lab``, ``STLOC``,``tabname`` - For non-layered elements, NTEMP is the number of corner nodes. + Use the :ref:`dim` command to define a table. For information on primary variables for each load + type, see `Applying Loads Using Tabular Input + `_ - The temperatures apply to element items with a starting location of - STLOC + n, where n is the value field location (VALn) of the table name - input. + For ``Lab`` = TEMP, each table defines ``NTEMP`` temperatures, as follows: - For layered elements, a single BFE command returns temperatures for one - layer interface. Multiple BFE commands are necessary for defining all - layered temperatures. + * For layered elements, ``NTEMP`` is the number of layer interface corners that allow temperature + input. - For beam, pipe and elbow elements that allow multiple temperature - inputs per node, define the tabular load for the first node only (Node - I), as loads on the remaining nodes are applied automatically. For - example, to specify a tabular temperature load on a PIPE288 element - with the through-wall-gradient option (KEYOPT(1) = 0), the BFE command - looks like this: + * For non-layered elements, ``NTEMP`` is the number of corner nodes. - BFE,Elem,TEMP,1,%tabOut%, %tabIn% + The temperatures apply to element items with a starting location of ``STLOC`` + ``n``, where n is + the value field location ( ``VALn`` ) of the table name input. - When a tabular function load is applied to an element, the load does - not vary according to the positioning of the element in space. + For layered elements, a single :ref:`bfe` command returns temperatures for one layer interface. + Multiple :ref:`bfe` commands are necessary for defining all layered temperatures. - Graphical picking is available only via the listed menu paths. + For beam, pipe and elbow elements that allow multiple temperature inputs per node, define the + tabular load for the first node only (Node I), as loads on the remaining nodes are applied + automatically. For example, to specify a tabular temperature load on a ``PIPE288`` element with the + through-wall-gradient option (KEYOPT(1) = 0), the :ref:`bfe` command looks like this: + + :ref:`bfe`, ``Elem``,TEMP,1,``tabOut``, ``tabIn%`` + + where % + + ``tabOut`` and ``tabIn`` and are the tables applied to the outer and inner surfaces of the pipe + wall, respectively. + + When a tabular function load is applied to an element, the load does not vary according to the + positioning of the element in space. + + 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. This command is also valid in PREP7. """ command = f"BFE,{elem},{lab},{stloc},{val1},{val2},{val3},{val4}" return self.run(command, **kwargs) - def bfecum(self, lab="", oper="", fact="", tbase="", **kwargs): - """Specifies whether to ignore subsequent element body force loads. + def bfecum( + self, lab: str = "", oper: str = "", fact: str = "", tbase: str = "", **kwargs + ): + r"""Specifies whether to ignore subsequent element body force loads. + + Mechanical APDL Command: `BFECUM `_ + + **Command default:** - APDL Command: BFECUM + .. _BFECUM_default: + + Replace previous values. Parameters ---------- - lab - Valid body load label. If ALL, use all appropriate labels. + lab : str + Valid body load label. If ALL, use all appropriate labels. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - oper + oper : str Replace or ignore key: - REPL - Subsequent values replace the previous values (default). + * ``REPL`` - Subsequent values replace the previous values (default). + + * ``IGNO`` - Subsequent values are ignored. + + fact : str + Scale factor for the element body load values. Zero (or blank) defaults to 1.0. Use a small + number for a zero scale factor. The scale factor is not applied to body load phase angles. - IGNO - Subsequent values are ignored. + tbase : str + Used (only with ``Lab`` = TEMP) to calculate the temperature used in the add or replace operation + (see ``Oper`` ) as: - fact - Scale factor for the element body load values. Zero (or blank) - defaults to 1.0. Use a small number for a zero scale factor. The - scale factor is not applied to body load phase angles. + Temperature = ``TBASE`` + ``FACT`` \* ( ``T`` - ``TBASE`` ) - tbase - Used (only with Lab = TEMP) to calculate the temperature used in - the add or replace operation (see Oper) as: + where ``T`` is the temperature specified on subsequent :ref:`bfe` commands. ``TBASE`` defaults to + zero. Notes ----- - Allows repeated element body force loads to be replaced or ignored. - Element body loads are applied with the BFE command. Issue the BFELIST - command to list the element body loads. The operations occur when the - next body loads are defined. For example, issuing the BFE command with - a temperature value of 25 after a previous BFE command with a - temperature value of 20 causes the new value of that temperature to be - 25 with the replace operation, or 20 with the ignore operation. A - scale factor is also available to multiply the next value before the - replace operation. A scale factor of 2.0 with the previous "replace" - example results in a temperature of 50. The scale factor is applied - even if no previous values exist. Issue BFECUM,STAT to show the - current label, operation, and scale factors. - - BFECUM does not work for tabular boundary conditions. + + .. _BFECUM_notes: + + Allows repeated element body-force loads to be replaced or ignored. Element body loads are applied + with the :ref:`bfe` command. Issue the :ref:`bfelist` command to list the element body loads. The + operations occur when the next body loads are defined. For example, issuing the :ref:`bfe` command + with a temperature value of 25 after a previous :ref:`bfe` command with a temperature value of 20 + causes the new value of that temperature to be 25 with the replace operation, or 20 with the ignore + operation. A scale factor is also available to multiply the next value before the replace operation. + A scale factor of 2.0 with the previous "replace" example results in a temperature of 50. The scale + factor is applied even if no previous values exist. Issue :ref:`bfecum`,STAT to show the current + label, operation, and scale factors. + + :ref:`bfecum` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"BFECUM,{lab},{oper},{fact},{tbase}" return self.run(command, **kwargs) - def bfedele(self, elem="", lab="", **kwargs): - """Deletes element body force loads. + def bfedele(self, elem: str = "", lab: str = "", **kwargs): + r"""Deletes element body-force loads. - APDL Command: BFEDELE + Mechanical APDL Command: `BFEDELE `_ Parameters ---------- - elem - Element at which body load is to be deleted. If ALL, delete for - all selected elements [ A component name may also be substituted - for ELEM. + elem : str + Element at which body load is to be deleted. If ALL, delete for all selected elements [ A + component name may also be substituted for ``ELEM``. - lab - Valid body load label. If ALL, use all appropriate labels. See BFE - command for labels. + lab : str + Valid body load label. If ALL, use all appropriate labels. See :ref:`bfe` command for labels. Notes ----- - Deletes element body force loads for a specified element and label. - Element body loads may be defined with the BFE commands. - Graphical picking is available only via the listed menu paths. + .. _BFEDELE_notes: + + Deletes element body-force loads for a specified element and label. Element body loads may be + defined with the :ref:`bfe` commands. This command is also valid in PREP7. """ command = f"BFEDELE,{elem},{lab}" return self.run(command, **kwargs) - def bfelist(self, elem="", lab="", **kwargs): - """Lists the element body force loads. + def bfelist(self, elem: str = "", lab: str = "", **kwargs): + r"""Lists the element body-force loads. - APDL Command: BFELIST + Mechanical APDL Command: `BFELIST `_ Parameters ---------- - elem - Element at which body load is to be listed. If ALL (or blank), - list for all selected elements [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. + elem : str + Element at which body load is to be listed. If ALL (or blank), list for 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``. - lab - Valid body load label. If ALL (or blank), use all appropriate - labels. See BFE command for labels. + lab : str + Valid body load label. If ALL (or blank), use all appropriate labels. See :ref:`bfe` command for + labels. Notes ----- - Lists the element body force loads for the specified element and label. - Element body loads may be defined with the BFE command. + + .. _BFELIST_notes: + + Lists the element body-force loads for the specified element and label. Element body loads may be + defined with the :ref:`bfe` command. This command is valid in any processor. """ command = f"BFELIST,{elem},{lab}" return self.run(command, **kwargs) - def bfescal(self, lab="", fact="", tbase="", **kwargs): - """Scales element body force loads. + def bfescal(self, lab: str = "", fact: str = "", tbase: str = "", **kwargs): + r"""Scales element body-force loads. - APDL Command: BFESCAL + Mechanical APDL Command: `BFESCAL `_ Parameters ---------- - lab - Valid body load label. If ALL, use all appropriate labels. + lab : str + Valid body load label. If ALL, use all appropriate labels. - fact - Scale factor for the element body load values. Zero (or blank) - defaults to 1.0. Use a small number for a "zero" scale factor. - The scale factor is not applied to body load phase angles. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - tbase - Base temperature for temperature difference. Used only with Lab = - TEMP. Scale factor is applied to the temperature difference (T - - TBASE) and then added to TBASE. T is the current temperature. + fact : str + Scale factor for the element body load values. Zero (or blank) defaults to 1.0. Use a small + number for a "zero" scale factor. The scale factor is not applied to body load phase angles. + + tbase : str + Base temperature for temperature difference. Used only with ``Lab`` = TEMP. Scale factor is + applied to the temperature difference ( ``T`` - ``TBASE`` ) and then added to ``TBASE``. ``T`` + is the current temperature. Notes ----- - Scales element body force loads on the selected elements in the - database. Issue the BFELIST command to list the element body loads. - Solid model boundary conditions are not scaled by this command, but - boundary conditions on the FE model are scaled. (Note that such scaled - FE boundary conditions may still be overwritten by unscaled solid model - boundary conditions if a subsequent boundary condition transfer - occurs.) - BFESCAL does not work for tabular boundary conditions. + .. _BFESCAL_notes: + + Scales element body-force loads on the selected elements in the database. Issue the :ref:`bfelist` + command to list the element body loads. Solid model boundary conditions are not scaled by this + command, but boundary conditions on the FE model are scaled. (Note that such scaled FE boundary + conditions may still be overwritten by unscaled solid model boundary conditions if a subsequent + boundary condition transfer occurs.) + + :ref:`bfescal` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"BFESCAL,{lab},{fact},{tbase}" return self.run(command, **kwargs) - def bflist(self, node="", lab="", **kwargs): - """Lists the body force loads on nodes. + def bflist(self, node: str = "", lab: str = "", **kwargs): + r"""Lists the body-force loads on nodes. - APDL Command: BFLIST + Mechanical APDL Command: `BFLIST `_ Parameters ---------- - node - Node at which body load is to be listed. If ALL (or blank), list - for all selected nodes [NSEL]. If NODE = P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). A component name may also be substituted for NODE. + node : str + Node at which body load is to be listed. If ALL (or blank), list for all selected nodes ( + :ref:`nsel` ). If ``Node`` = P, graphical picking is enabled and all remaining command fields + are ignored (valid only in the GUI). You can substitute a component name for ``Node``. - lab - Valid body load label. If ALL (or blank), use all appropriate - labels. See the BF command for labels. In an explicit dynamic - analysis, the only valid body load label is TEMP. + lab : str + Valid body load label. If ALL (or blank), use all appropriate labels. (See :ref:`bf`.) Notes ----- - Lists the body force loads for the specified node and label. Nodal - body loads may be defined with the BF command (except in an explicit - dynamic analysis). - The command BFLIST,TEMP can be used in an explicit dynamic analysis to - list temperature loads that are read in by the LDREAD command. BFLIST - cannot be used to list temperature loads defined by the EDLOAD command - (use EDLOAD,LIST to list this type of load). + .. _BFLIST_notes: + + Lists the body-force loads for the specified node and label. Nodal body loads are defined via + :ref:`bf`. This command is valid in any processor. """ command = f"BFLIST,{node},{lab}" return self.run(command, **kwargs) - def bfscale(self, lab="", fact="", tbase="", **kwargs): - """Scales body force loads at nodes. + def bfport(self, cmname: str = "", **kwargs): + r"""Transfers a thermal body-force load (HGEN) from selected ``MESH200`` elements to reinforcing + elements. - APDL Command: BFSCALE + Mechanical APDL Command: `BFPORT `_ Parameters ---------- - lab - Valid body load label. If ALL, use all appropriate labels. - - fact - Scale factor for the nodal body load values. Zero (or blank) - defaults to 1.0. Use a small number for a zero scale factor. The - scale factor is not applied to body load phase angles. - - tbase - Base temperature for temperature difference. Used only with Lab = - TEMP. Scale factor is applied to the temperature difference (T - - TBASE) and then added to TBASE. T is the current temperature. + cmname : str + Component name containing a list of selected ``MESH200`` elements. Notes ----- - Scales body force loads in the database on the selected nodes. Issue - the BFLIST command to list the nodal body loads. Solid model boundary - conditions are not scaled by this command, but boundary conditions on - the FE model are scaled. - Note:: : Such scaled FE boundary conditions may still be overwritten by - unscaled solid model boundary conditions if a subsequent boundary - condition transfer occurs. + .. _BFPORT_notes: - BFSCALE does not work for tabular boundary conditions. + This command transfers a thermal body-force load (HGEN) from selected ``MESH200`` elements to + associated reinforcing elements or members (individual reinforcings). The association is established + via :ref:`ereinf` using the `mesh-independent method + `_ for + defining reinforcing. - This command is also valid in PREP7. - """ - command = f"BFSCALE,{lab},{fact},{tbase}" - return self.run(command, **kwargs) + Issue this command after issuing :ref:`ereinf`. - def bfunif(self, lab="", value="", **kwargs): - """Assigns a uniform body force load to all nodes. - - APDL Command: BFUNIF - - Parameters - ---------- - lab - Valid body load label. If ALL, use all appropriate labels. + Select ``MESH200`` elements by issuing this command and specifying the component, or by issuing + :ref:`esel`. (If you specify a component name, :ref:`esel` is ignored.) - value - Uniform value associated with Lab item, or table name when - specifying tabular boundary conditions. To specify a table, - enclose the table name in percent signs (%), e.g., - BFUNIF,Lab,%tabname%. + This command supports a thermal body-force load (HGEN) only. - Notes - ----- - In a transient or nonlinear thermal analysis, the uniform temperature - is used during the first iteration of a solution as follows: (a) as - the starting nodal temperature (except where temperatures are - explicitly specified [D, DK]), and (b) to evaluate temperature- - dependent material properties. In a structural analysis or explicit - dynamic analysis, the uniform temperature is used as the default - temperature for thermal strain calculations and material property - evaluation (except where body load temperatures are specified [BF, BFE, - BFK, LDREAD]). In other scalar field analyses, the uniform temperature - is used for material property evaluation. - - When the command BFUNIF,TEMP is used in an explicit dynamic analysis, - you cannot use the EDLOAD,TEMP command to apply temperature loading. - Furthermore, any temperature loading defined by BFUNIF cannot be listed - or deleted by the EDLOAD command. - - An alternate command, TUNIF, may be used to set the uniform temperature - instead of BFUNIF,TEMP. Since TUNIF (or BFUNIF,TEMP) is step-applied in - the first iteration, you should use BF, ALL, TEMP, Value to ramp on a - uniform temperature load. - - You can specify a table name only when using temperature (TEMP), heat - generation rate (HGEN), and diffusing substance generation rate (DGEN) - body load labels. When using TEMP, you can define a one-dimensional - table that varies with respect to time (TIME) only. When defining this - table, enter TIME as the primary variable. No other primary variables - are valid. Tabular boundary conditions cannot be used in an explicit - dynamic analysis. + To define the thermal body-force load on ``MESH200`` elements, issue :ref:`bfe` or :ref:`bf`. This command is also valid in PREP7. """ - command = f"BFUNIF,{lab},{value}" + command = f"BFPORT,{cmname}" return self.run(command, **kwargs) - def ldread( - self, - lab="", - lstep="", - sbstep="", - time="", - kimg="", - fname="", - ext="", - **kwargs, - ): - """Reads results from the results file and applies them as loads. + def bfscale(self, lab: str = "", fact: str = "", tbase: str = "", **kwargs): + r"""Scales body-force loads at nodes. - APDL Command: LDREAD + Mechanical APDL Command: `BFSCALE `_ Parameters ---------- - lab - Valid load label: - - TEMP - Temperatures from a thermal analysis are applied as body force nodal loads (BF) - in a structural analysis, an explicit dynamic analysis, or - other type of analysis. - - If the thermal analysis uses SHELL131 or SHELL132, temperatures are applied as body force element loads (BFE). In most cases, only the top and bottom temperatures from SHELL131 and SHELL132 are used by the structural shell elements; any interior temperatures are ignored. - All temperatures are used for SHELL181 using section input, and SHELL281 using - section input; for these elements, therefore, the - number of temperature points at a node generated - in the thermal model must match the number of - temperature points at a node needed by the - structural model. + lab : str + Valid body load label. If ALL, use all appropriate labels. - When using SHELL131 or SHELL132 information for the LDREAD operation, all element types should specify the same set of thermal degrees of freedom. - When used in conjunction with KIMG=1 and KIMG=2, temperatures can be applied to - a subsequent thermal analysis as nodal loads (D) - or initial conditions (IC), respectively. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - FORC - Forces from an electromagnetic analysis are applied as force loads (F) in a - structural analysis. LDREAD,FORC reads coupling forces. See - the discussion on force computation in the Low-Frequency - Electromagnetic Analysis Guide. + fact : str + Scale factor for the nodal body load values. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. The scale factor is not applied to body load phase angles. - For a full harmonic magnetic analysis, FORC represents the time-averaged force (use in conjunction with KIMG = 2). Values are in the nodal coordinate system for the force loads (F). - HGEN + tbase : str + Base temperature for temperature difference. Used only with ``Lab`` = TEMP. Scale factor is + applied to the temperature difference ( ``T`` - ``TBASE`` ) and then added to ``TBASE``. ``T`` + is the current temperature. - Heat generations from an electromagnetic analysis are applied as body force loads (BFE) in a thermal analysis. For a full harmonic analysis, HGEN represents the time-averaged heat generation load (use in conjunction with KIMG = 2). - JS + Notes + ----- - Source current density from a current-conduction analysis are applied as body force loads (BFE). Values are in the global Cartesian coordinate system. - EF + .. _BFSCALE_notes: - Electric field element centroid values from an electrostatic analysis are applied as body force loads (BFE) in a magnetic analysis. Values are in the global Cartesian coordinate system. - REAC + Scales body-force loads in the database on the selected nodes. Issue the :ref:`bflist` command to + list the nodal body loads. Solid model boundary conditions are not scaled by this command, but + boundary conditions on the FE model are scaled. Such scaled FE boundary conditions may still be + overwritten by unscaled solid model boundary conditions if a subsequent boundary condition transfer + occurs. - Reaction loads from any analysis are applied as force loads (F) in any analysis. Values are in the nodal coordinate system. - CONC + :ref:`bfscale` does not work for tabular boundary conditions. - lstep - Load step number of the data set to be read. Defaults to 1. If - LAST, ignore SBSTEP and TIME and read the last data set. + This command is also valid in PREP7. + """ + command = f"BFSCALE,{lab},{fact},{tbase}" + return self.run(command, **kwargs) - sbstep - Substep number (within LSTEP). If zero (or blank), LSTEP - represents the last substep of the load step. + def bfunif(self, lab: str = "", value: str = "", **kwargs): + r"""Assigns a uniform body-force load to all nodes. - time - Time-point identifying the data set to be read. Used only if both - LSTEP and SBSTEP are zero (or blank). If TIME is between two - solution time points on the results file, a linear interpolation is - done between the two data sets. If TIME is beyond the last time - point on the file, use the last time point. + Mechanical APDL Command: `BFUNIF `_ - kimg - When used with results from harmonic analyses (ANTYPE,HARMIC) KIMG - establishes which set of data to read: + **Command default:** - 0 - Read the real part of the solution. Valid also for Lab = EHFLU to read in - time-average heat flux. + .. _BFUNIF_default: - 1 - Read the imaginary part of the solution. + Set TEMP to the reference temperature ( :ref:`tref` but not :ref:`mp`,REFT), and FLUE and HGEN to + zero. - 2 - Calculate and read the time-average part. Meaningful for Lab = HGEN or FORC. + Parameters + ---------- + lab : str + Valid body load label. If ALL, use all appropriate labels. - fname - File name and directory path (248 characters maximum, including the - characters needed for the directory path). An unspecified - directory path defaults to the working directory; in this case, you - can use all 248 characters for the file name. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. - ext - Filename extension (eight-character maximum). + value : str + Uniform value associated with ``Lab`` item, or table name when specifying tabular boundary + conditions. To specify a table, enclose the table name in percent signs (%), for example, + :ref:`bfunif`, ``Lab``,``tabname``. Notes ----- - The LDREAD command reads results data from the results file and applies - them as loads. - The command can also apply results from an analysis defined with one - physics environment as loads on a second analysis using a different - physics environment. Results values are applied as loads for field- - coupling effects (for example, output temperatures from a thermal - analysis as input to a structural analysis). + .. _BFUNIF_notes: - The command works based on the assumption that the meshes have not - changed. + In a transient or nonlinear thermal analysis, the uniform temperature is used during the first + iteration of a solution as follows: (a) as the starting nodal temperature except where temperatures + are explicitly specified ( :ref:`d`, :ref:`dk` ), and (b) to evaluate temperature-dependent material + properties. In a structural analysis, the uniform temperature is used as the default temperature for + thermal strain calculations and material property evaluation except where body load temperatures are + specified ( :ref:`bf`, :ref:`bfe`, :ref:`bfk`, :ref:`ldread` ). In other scalar field analyses, the + uniform temperature is used for material property evaluation. - Nodal loads are applied only to selected nodes. Element loads are - applied only to selected elements. Element surface loads are applied - only to selected elements where all face nodes for that surface are - selected. + An alternate command, :ref:`tunif`, may be used to set the uniform temperature instead of + :ref:`bfunif`,TEMP. Since :ref:`tunif` (or :ref:`bfunif`,TEMP) is step-applied in the first + iteration, you should use :ref:`bf`, ALL, TEMP, Value to ramp on a uniform temperature load. - To assure proper distribution of the surface loads, select only the - nodes on the element face where the surface load is to be applied. + You can specify a table name only when using temperature (TEMP), heat generation rate (HGEN), and + diffusing substance generation rate (DGEN) body load labels. When using TEMP, you can define a one- + dimensional table that varies with respect to time (TIME) only. When defining this table, enter TIME + as the primary variable. No other primary variables are valid. - Scaling and accumulation specifications are applied as the loads are - read via the following commands: + 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. - BFCUM for body force loads. (Heat-generation loads are not - accumulated.) + This command is also valid in PREP7. """ - command = f"LDREAD,{lab},{lstep},{sbstep},{time},{kimg},{fname},{ext}" + command = f"BFUNIF,{lab},{value}" return self.run(command, **kwargs) - def rimport( - self, - source="", - type_="", - loc="", - lstep="", - sbstep="", - fname="", - ext="", - spscale="", - mscale="", - **kwargs, - ): - """Imports initial stresses from an explicit dynamics run into ANSYS. + def tunif(self, temp: str = "", **kwargs): + r"""Assigns a uniform temperature to all nodes. - APDL Command: RIMPORT + Mechanical APDL Command: `TUNIF `_ Parameters ---------- - source - The type of analysis run from which stresses are imported. - - OFF - Ignore initial stresses. - - DYNA - Get initial stresses from an earlier explicit - (ANSYS LS-DYNA) run (default). - - type\\_ - Type of data imported. Note that this is an ANSYS-defined - field; the only valid value is STRESS. - - loc - Location where the data is imported. Note that this is an - ANSYS- defined field; the only valid value is ELEM (data - imported at the element integration points). - - lstep - Load step number of data to be imported. Defaults to the - last load step. - - sbstep - Substep number of data to be imported. Defaults to the - last substep. - - fname - File name and directory path (248 characters maximum, - including the characters needed for the directory path). - An unspecified directory path defaults to the working - directory; in this case, you can use all 248 characters - for the file name. - - ext - Filename extension (eight-character maximum). - - spscale - Stabilization factor. This factor is used in a springback - analysis to scale (up or down) the initial stiffness of - the applied spring. No default; input a value only if you - want to activate stabilization. If SPSCALE is blank, - stabilization is not activated. - - mscale - Acceptable stabilization stiffness (defaults to 1.0 X - 10--4). In a springback analysis, iterations will stop - when the applied spring stiffness comes down to this - value. MSCALE is not used if SPSCALE is blank. + temp : str + Uniform temperature assigned to the nodes. If a ``TEMP`` value is not specified, the uniform + temperature is set to zero. Notes ----- - This command imports initial stress information into ANSYS - from an earlier explicit (ANSYS LS-DYNA) run. The stress - state from SHELL163 and SOLID164 elements in the explicit - analysis is imported to the corresponding SHELL181 and - SOLID185 implicit elements. For the shell elements, the - current shell element thickness is also imported. This command - is valid only before the first SOLVE command of the implicit - analysis (which comes after the explicit analysis) and is - ignored if issued after subsequent SOLVE commands (that is, - stresses will not be re-imported). - - RIMPORT is typically used to perform springback analysis of - sheet metal forming. We recommend that you use SHELL163 - elements in the explicit analysis with 3 to 5 integration - points through the thickness. This ensures that the - through-thickness stress distribution is transferred - accurately to the SHELL181 elements. If more than 5 - integration points are used, ANSYS imports resultants (forces - and moments) to the SHELL181 elements. This implies that - linearization of the through-thickness stress distribution is - assumed in SHELL181 elements. If SHELL163 uses full - integration in the shell plane, stress and thickness data are - averaged and then transferred. For the solid elements, the - stress at the SOLID164 element centroid is transferred to the - SOLID185 element centroid. If SOLID164 has full integration, - the stress is averaged and then transferred. - - When the SPSCALE argument is specified, artificial springs - with exponentially decaying stiffness (as a function of - iterations) are applied. This technique is recommended only - for those cases in which there are severe convergence - difficulties. In general, you should first attempt a - springback analysis without using the stabilization factors - SPSCALE and MSCALE. (For more information on springback - stabilization, see the ANSYS LS-DYNA User's Guide.) - - This command is not written to the Jobname.CDB file when the - CDWRITE command is issued. Further, the RIMPORT information is - not saved to the database; therefore, the RIMPORT command must - be reissued if the database is resumed. - - This command is also valid in PREP7. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"RIMPORT,{source},{type_},{loc},{lstep},{sbstep},{fname},{ext},,{spscale},{mscale}" - return self.run(command, **kwargs) - - def tunif(self, temp="", **kwargs): - """Assigns a uniform temperature to all nodes. - - APDL Command: TUNIF - Parameters - ---------- - temp - Uniform temperature assigned to the nodes. If a TEMP value is not - specified, the uniform temperature is set to zero. + .. _TUNIF_notes: - Notes - ----- - TUNIF is a convenient form of the more general BFUNIF command. + :ref:`tunif` is a convenient form of the more general :ref:`bfunif` command. - In a transient or nonlinear thermal analysis, the uniform temperature - is used during the first iteration of a solution as follows: + In a transient or nonlinear thermal analysis, the uniform temperature is used during the first + iteration of a solution as follows: - as the starting nodal temperature (except where temperatures are - explicitly specified [D, DK]), + * as the starting nodal temperature, except where temperatures are explicitly specified ( :ref:`d`, + :ref:`dk` ) - to evaluate temperature-dependent material properties. + * to evaluate temperature-dependent material properties. - In a structural analysis or an explicit dynamic analysis, the uniform - temperature is used as the default temperature for thermal strain - calculations and material property evaluation (except where body load - temperatures are specified (BF, BFE, BFK, LDREAD). In other scalar - field analyses, the uniform temperature is used for material property - evaluation. + In a structural analysis, the uniform temperature is used as the + default temperature for thermal strain calculations and material property evaluation, except where body load + temperatures are specified ( :ref:`bf`, :ref:`bfe`, :ref:`bfk`, :ref:`ldread` ). In other scalar + field analyses, the uniform temperature is used for material property evaluation. - Because TUNIF (or BFUNIF,TEMP) is step-applied in the first iteration, - issue a BF,ALL,TEMP,Value command to ramp on a uniform temperature - load. + Because :ref:`tunif` (or :ref:`bfunif`,TEMP) is step-applied in the first iteration, issue a + :ref:`bf`,ALL,TEMP, ``Value`` command to ramp on a uniform temperature load. - When the TUNIF command is used in an explicit dynamic analysis, you - cannot apply temperature loading via the EDLOAD,,TEMP command. - Furthermore, temperature loading defined by TUNIF cannot be listed or - deleted by the EDLOAD command. + The command default sets the uniform temperature to the reference temperature defined via the + :ref:`tref` command only (and not the :ref:`mp`,REFT command). - The command default sets the uniform temperature to the reference - temperature defined via the TREF command only (and not the MP,REFT - command). + If using the command default to set the uniform temperature (to the reference temperature set via + :ref:`tref` ), you can convert temperature-dependent secant coefficients of thermal expansion + (SCTEs) from the definition temperature to the uniform temperature. To do so, issue the + :ref:`mpamod` command. - If using the command default to set the uniform temperature (to the - reference temperature set via TREF), you can convert temperature- - dependent secant coefficients of thermal expansion (SCTEs) from the - definition temperature to the uniform temperature. To do so, issue the - MPAMOD command. + 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. This command is also valid in PREP7. """ diff --git a/src/ansys/mapdl/core/_commands/solution/fe_constraints.py b/src/ansys/mapdl/core/_commands/solution/fe_constraints.py index 03c3a1fc414..9ce243d6252 100644 --- a/src/ansys/mapdl/core/_commands/solution/fe_constraints.py +++ b/src/ansys/mapdl/core/_commands/solution/fe_constraints.py @@ -22,747 +22,1133 @@ class FeConstraints: + def d( self, - node="", - lab="", - value="", - value2="", - nend="", - ninc="", - lab2="", - lab3="", - lab4="", - lab5="", - lab6="", + node: str = "", + lab: str = "", + value: str = "", + value2: str = "", + nend: str = "", + ninc: str = "", + lab2: str = "", + lab3: str = "", + lab4: str = "", + lab5: str = "", + lab6: str = "", + meshflag: str = "", **kwargs, ): - """Defines degree-of-freedom constraints at nodes. + r"""Defines degree-of-freedom constraints at nodes. - APDL Command: D + Mechanical APDL Command: `D `_ Parameters ---------- - node - Node at which constraint is to be specified. If ALL, NEND and NINC - are ignored and constraints are applied to all selected nodes - (NSEL). If Node = P, graphical picking is enabled and all remaining - command fields are ignored (valid only in the GUI). A component - name may also be substituted for Node. - - lab - Valid degree-of-freedom label. If ALL, use all appropriate labels. - - value - Degree-of-freedom value or table name reference for tabular - boundary conditions. To specify a table, enclose the table name in - percent (%) signs (for example, D,Node,TEMP,%tabname%). Use the - ``*DIM`` command to define a table. - - value2 - Second degree-of-freedom value (if any). If the analysis type and - the degree of freedom allow a complex input, Value (above) is the - real component and VALUE2 is the imaginary component. - - nend, ninc - Specifies the same values of constraint at the range of nodes from - Node to NEND (defaults to Node), in steps of NINC (defaults to 1). - - lab2, lab3, lab4, lab5, lab6 - Additional degree-of-freedom labels. The same values are applied to - the nodes for these labels. + node : str + Node at which constraint is to be specified. If ALL, ``NEND`` and ``NINC`` are ignored and + constraints are applied to all selected nodes ( :ref:`nsel` ). If ``Node`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``Node``. + + lab : str + Valid degree-of-freedom label. If ALL, use all appropriate labels. + + * **Structural labels** : UX, UY, or UZ (displacements); ROTX, ROTY, or ROTZ (rotations); WARP + (warping). + * **Thermal labels** : TEMP, TBOT, TE2, TE3,..., TTOP (temperature). + * **Electric labels** : VOLT (voltage); EMF (electromotive force). + * **Magnetic labels** : MAG (scalar magnetic potential); AZ (vector magnetic potential). + * **Acoustic labels** : PRES (pressure); UX, UY, or UZ (displacements for FSI coupled elements); + ENKE (acoustic energy density). + * **Pore fluid labels** : PRES (pore pressure); UX, UY, or UZ (displacements); TEMP (temperature). + * **Diffusion labels** : CONC (concentration). + + For structural static and transient analyses, translational and rotational velocities are also valid + loads. Use these labels: VELX, VELY, VELZ (translational velocities); OMGX, OMGY, OMGZ (rotational + velocities). + + For structural analyses, HDSP (hydrostatic pressure) is also valid. However, HDSP is not included + when ``Lab`` = ALL. + + For structural transient analyses, the following acceleration loads are also valid: ACCX, ACCY, ACCZ + (translational accelerations); DMGX, DMGY, DMGZ (rotational accelerations). The velocity and + acceleration loads are not included when ``Lab`` = ALL. + + If the node is connected to an ``ELBOW290`` element, the following pipe cross-section degree-of- + freedom labels are also valid: SE, SO, SW, SRA, and SRT. (For details, see the ``ELBOW290`` + documentation.) The degrees of freedom are not included when ``Lab`` = ALL. To constrain all cross- + section degrees of freedom, specify ``Lab`` = SECT. + + The PRES degree of freedom is also available for `porous media + `_ + problems. + + value : str + Degree-of-freedom value or table name reference for tabular boundary conditions. To specify a + table, enclose the table name in percent (%) signs (for example, :ref:`d`, + ``Node``,TEMP,``tabname``). To define a table, issue :ref:`dim`. + + If ``Value`` = SUPPORT, you can specify pseudo-constraints when `using residual vectors + `_ + in a modal analysis ( :ref:`resvec`,ON) or `CMS + `_ + analysis ( :ref:`cmsopt`,RFFB). + + If the enforced motion is active in the modal analysis ( :ref:`modcont`,,on), ``Value`` is the + base identification number. It should be an integer greater than or equal to 1 and less than + 10000. + + value2 : str + Second degree-of-freedom value (if any). If the analysis type and the degree of freedom allow a + complex input, ``Value`` (above) is the real component and ``VALUE2`` is the imaginary + component. + + nend : str + Specifies the same values of constraint at the range of nodes from ``Node`` to ``NEND`` + (defaults to ``Node`` ), in steps of ``NINC`` (defaults to 1). + + ninc : str + Specifies the same values of constraint at the range of nodes from ``Node`` to ``NEND`` + (defaults to ``Node`` ), in steps of ``NINC`` (defaults to 1). + + lab2 : str + Additional degree-of-freedom labels. The same values are applied to the nodes for these labels. + + lab3 : str + Additional degree-of-freedom labels. The same values are applied to the nodes for these labels. + + lab4 : str + Additional degree-of-freedom labels. The same values are applied to the nodes for these labels. + + lab5 : str + Additional degree-of-freedom labels. The same values are applied to the nodes for these labels. + + lab6 : str + Additional degree-of-freedom labels. The same values are applied to the nodes for these labels. + + meshflag : str + Specifies how to apply constraint on the mesh. Valid in a `nonlinear adaptivity analysis + `_ when ``Lab`` = + UX / UY / UZ and ``Node`` is not a component name. + + * 0 - Constraint applied on the current mesh (default). + * 1 - Constraint applied on the initial mesh for nonlinear adaptivity. ( ``NEND`` and ``NINC`` are + not valid.) Notes ----- - The available degrees of freedom per node are listed under "Degrees of - Freedom" in the input table for each element type in the Element - Reference. Degrees of freedom are defined in the nodal coordinate - system. The positive directions of structural translations and - rotations are along and about the positive nodal axes directions. - Structural rotations should be input in radians. The node and the - degree-of-freedom label must be selected (NSEL, DOFSEL). - - In a structural analysis, you can apply only one displacement, - velocity, or acceleration load at any degree of freedom. If multiple - loads are specified, the last applied load overrides the previous ones. - For example, the following commands apply loads to node 100: - - In this case, the velocity load (VELX) applied in the last command will - override the displacement load (UX). - - For elements used in static and low frequency electromagnetic analysis - (SOLID236 and SOLID237), the AZ degree of freedom is not a z-component - of a vector potential, but rather the flux contribution on the element - edge. To specify a flux-parallel condition, set AZ = 0. For more - information, see 3-D Magnetostatics and Fundamentals of Edge-based - Analysis in the Low-Frequency Electromagnetic Analysis Guide. - - In an explicit dynamic analysis, the D command can only be used to fix - nodes in the model. The degree-of-freedom value must be zero; no other - values are valid. Use the EDLOAD command to apply a nonzero - displacement in an explicit dynamic analysis. - - For ELBOW290 cross-section degrees of freedom (Lab = SE, SO, SW, SRA, - SRT, or SECT), the D command can only specify fixed constraints. The - degree-of-freedom value must be zero; no other values are valid. - - For hydrostatic fluid elements (HSFLD241 and HSFLD242), the HDSP - degree-of-freedom constraint at the pressure node prescribes the - pressure value for all the fluid elements sharing the pressure node. - - Tabular boundary conditions (VALUE = %tabname%) are available only for - the following degree-of-freedom labels: Electric (VOLT), structural - (UX, UY, UZ, ROTX, ROTY, ROTZ, and velocity and acceleration loads - VELX, VELY, VELZ, OMGX, OMGY, OMGZ, ACCX, ACCY, ACCZ, DMGX, DMGY, - DMGZ), acoustic (PRES, UX, UY, UZ,), and temperature (TEMP, TBOT, TE2, - TE3, . . ., TTOP). All labels are valid only in static (ANTYPE,STATIC) - and full transient (ANTYPE,TRANS) analyses. - - %_FIX% is an ANSYS reserved table name. When VALUE is set to %_FIX%, - ANSYS will prescribe the degree of freedom to the "current" relative - displacement value. This option is only valid for the following labels: - UX, UY, UZ, ROTX, ROTY, ROTZ. Alternatively, functions UX(), UY(), etc. - may be used (see ``*GET`` for a complete list of available functions). In - most cases, %_FIX% usage is efficient and recommended for all - structural degrees of freedom. - - When Value = SUPPORT, specify only the minimum number of displacement - constraints necessary to prevent rigid body motion: three constraints - (or fewer, depending on the element type) for 2-D models and six (or - fewer) for 3-D models. - - If constraints and initial conditions (IC) are applied at the same - node, the constraint specification overrides. This combination is - useful when a constraint degree-of-freedom value needs to start with a - nonzero value at time = 0.0. For example, if the constraint degree-of- - freedom value is prescribed to be a cosine function, then specifying an - initial condition for the same node and degree of freedom ensures that - the initial value for the constraint degree of freedom at time = 0.0 is - same as the cosine function evaluated at time = 0.0. If initial - conditions are not specified, the constraint degree-of-freedom value - ramps from zero in the first substep of the first loadstep. - - If more than one rotational degrees of freedom are constrained with - non-zero rotations (ROTX, ROTY, ROTZ), rotational velocities (OMGX, - OMGY, OMGZ), or rotational accelerations (DMGX, DMGY, DMGZ), then the - rotation of the constrained node from its initial configuration to its - final configuration depends on the combination and the sequence in - which the constraints are applied. See Rotations in a Large-Deflection - Analysis in Structural Analysis Guide. + + .. _D_notes: + + The available degrees of freedom per node are listed under **Degrees of Freedom** in the input table + for each element type in the `Element Reference + `_. Degrees of + freedom are defined in the + nodal coordinate system. The positive directions of structural translations and rotations are along + and about the positive nodal axes directions. Structural rotations should be input in radians. The + node and the degree-of-freedom label must be selected ( :ref:`nsel`, :ref:`dofsel` ). + + In a structural analysis, you can apply only one displacement, velocity, or acceleration load at any + degree of freedom. If multiple loads are specified, the last applied load overrides the previous + ones. For example, the following commands apply loads to node 100: + + * D,100,UX, ``Value`` + * D,100,VELX, ``Value`` + + In this case, the velocity load (VELX) applied in the last command will override the displacement + load (UX). + + For elements used in static and low frequency electromagnetic analysis ( ``SOLID236`` and + ``SOLID237`` ), the AZ degree of freedom is not a z-component of a vector potential, but rather the + flux contribution on the element edge. To specify a flux-parallel condition, set AZ = 0. For more + information, see `3D Magnetostatics and Fundamentals of Edge-based Analysis + `_ in + the `Low-Frequency Electromagnetic Analysis Guide + `_. + + For ``ELBOW290`` cross-section degrees of freedom ( ``Lab`` = SE, SO, SW, SRA, SRT, or SECT), the + :ref:`d` command can only specify fixed constraints. The degree-of-freedom value must be zero; no + other values are valid. + + For hydrostatic fluid elements ( ``HSFLD241`` and ``HSFLD242`` ), the HDSP degree-of-freedom + constraint at the pressure node prescribes the pressure value for all the fluid elements sharing the + pressure node. + + Tabular boundary conditions ( ``VALUE`` = ``tabname``) are available only for the following degree- + of-freedom labels: Electric (VOLT), structural (UX, UY, UZ, ROTX, ROTY, ROTZ, and velocity and + acceleration loads VELX, VELY, VELZ, OMGX, OMGY, OMGZ, ACCX, ACCY, ACCZ, DMGX, DMGY, DMGZ), acoustic + (PRES, UX, UY, UZ, ENKE ), temperature (TEMP, TBOT, TE2, TE3,..., TTOP), diffusion (CONC). All + labels are valid only in static ( :ref:`antype`,STATIC) and full transient ( :ref:`antype`,TRANS) + analyses. + + In a mode-superposition harmonic or transient analysis, you must apply the constraints in the modal + portion of the analysis for residual vector ( `Using the Residual Vector or the Residual Response + Method to Improve Accuracy + `_ + `Enforced Motion Method for Mode-Superposition Transient and Harmonic Analyses + `_ + + %_FIX% is a Mechanical APDL reserved table name. When ``VALUE`` is set to %_FIX%, the program + prescribes + the degree of freedom to the current relative displacement value. This option is valid for the + following labels: UX, UY, UZ, ROTX, ROTY, ROTZ. Alternatively, functions UX(), UY(), etc. can be + used. (See :ref:`get` for a list of available functions.) In most cases, %_FIX% usage is efficient + and recommended for all structural degrees of freedom. + + When ``Value`` = SUPPORT, specify only the minimum number of displacement constraints necessary to + prevent rigid body motion: three constraints (or fewer, depending on the element type) for 2D models + and six (or fewer) for 3D models. + + If constraints and initial conditions ( :ref:`ic` ) are applied at the same node, the constraint + specification overrides. This combination is useful when a constraint degree-of-freedom value needs + to start with a nonzero value at time = 0.0. For example, if the constraint degree-of-freedom value + is prescribed to be a cosine function, then specifying an initial condition for the same node and + degree of freedom ensures that the initial value for the constraint degree of freedom at time = 0.0 + is same as the cosine function evaluated at time = 0.0. If initial conditions are not specified, the + constraint degree-of-freedom value ramps from zero in the first substep of the first load step. + + If more than one rotational degrees of freedom are constrained with non-zero rotations (ROTX, ROTY, + ROTZ), rotational velocities (OMGX, OMGY, OMGZ), or rotational accelerations (DMGX, DMGY, DMGZ), + then the rotation of the constrained node from its initial configuration to its final configuration + depends on the combination and the sequence in which the constraints are applied. See Rotations in a + Large-Deflection Analysis in `Structural Analysis Guide + `_. This command is also valid in PREP7. """ - command = f"D,{node},{lab},{value},{value2},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6}" + command = f"D,{node},{lab},{value},{value2},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6},{meshflag}" return self.run(command, **kwargs) - def dcum(self, oper="", rfact="", ifact="", tbase="", **kwargs): - """Specifies that DOF constraint values are to be accumulated. + def dcum( + self, + oper: str = "", + rfact: str = "", + ifact: str = "", + tbase: str = "", + **kwargs, + ): + r"""Specifies that DOF constraint values are to be accumulated. + + Mechanical APDL Command: `DCUM `_ + + **Command default:** + + .. _DCUM_default: - APDL Command: DCUM + Replace previous values. Parameters ---------- - oper + oper : str Accumulation key: - REPL - Subsequent values replace the previous values (default). + * ``REPL`` - Subsequent values replace the previous values (default). - ADD - Subsequent values are added to the previous values. + * ``ADD`` - Subsequent values are added to the previous values. - IGNO - Subsequent values are ignored. + * ``IGNO`` - Subsequent values are ignored. - rfact - Scale factor for the real component. Zero (or blank) defaults to - 1.0. Use a small number for a zero scale factor. + rfact : str + Scale factor for the real component. Zero (or blank) defaults to 1.0. Use a small number for a + zero scale factor. - ifact - Scale factor for the imaginary component. Zero (or blank) defaults - to 1.0. Use a small number for a zero scale factor. + ifact : str + Scale factor for the imaginary component. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. - tbase - Base temperature for temperature difference. Used only with - temperature degree of freedom. Scale factor is applied to the - temperature difference (T-TBASE) and then added to TBASE. T is the - current temperature. + tbase : str + Base temperature for temperature difference. Used only with temperature degree of freedom. Scale + factor is applied to the temperature difference ( ``T`` - ``TBASE`` ) and then added to + ``TBASE``. ``T`` is the current temperature. Notes ----- - Allows repeated degree of freedom constraint values (displacement, - temperature, etc.) to be replaced, added, or ignored. Operations - apply to the selected nodes [NSEL] and the selected degree of freedom - labels [DOFSEL]. This command also operates on velocity and - acceleration loads applied in a structural analysis. - - The operations occur when the next degree of freedom constraints are - defined. For example, issuing the command D,1,UX,.025 after a previous - D,1,UX,.020 causes the new value of the displacement on node 1 in the - x-direction to be 0.045 with the add operation, 0.025 with the replace - operation, or 0.020 with the ignore operation. Scale factors are also - available to multiply the next value before the add or replace - operation. A scale factor of 2.0 with the previous "add" example - results in a displacement of 0.070. Scale factors are applied even if - no previous values exist. Issue DCUM,STAT to show the current label, - operation, and scale factors. Solid model boundary conditions are not - affected by this command, but boundary conditions on the FE model are - affected. - - Note:: : FE boundary conditions may still be overwritten by existing - solid model boundary conditions if a subsequent boundary condition - transfer occurs. - - DCUM does not work for tabular boundary conditions. + + .. _DCUM_notes: + + Allows repeated degree of freedom constraint values (displacement, temperature, etc.) to be + replaced, added, or ignored. Operations apply to the selected nodes ( :ref:`nsel` ) and the selected + degree of freedom labels ( :ref:`dofsel` ). This command also operates on velocity and acceleration + loads applied in a structural analysis. + + The operations occur when the next degree of freedom constraints are defined. For example, issuing + the command :ref:`d`,1,UX,.025 after a previous :ref:`d`,1,UX,.020 causes the new value of the + displacement on node 1 in the x-direction to be 0.045 with the add operation, 0.025 with the replace + operation, or 0.020 with the ignore operation. Scale factors are also available to multiply the next + value before the add or replace operation. A scale factor of 2.0 with the previous "add" example + results in a displacement of 0.070. Scale factors are applied even if no previous values exist. + Issue :ref:`dcum`,STAT to show the current label, operation, and scale factors. Solid model boundary + conditions are not affected by this command, but boundary conditions on the FE model are affected. + FE boundary conditions may still be overwritten by existing solid model boundary conditions if a + subsequent boundary condition transfer occurs. + + :ref:`dcum` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"DCUM,{oper},{rfact},{ifact},{tbase}" return self.run(command, **kwargs) - def ddele(self, node="", lab="", nend="", ninc="", rkey="", **kwargs): - """Deletes degree-of-freedom constraints. + def ddele( + self, + node: str = "", + lab: str = "", + nend: str = "", + ninc: str = "", + rkey: str = "", + **kwargs, + ): + r"""Deletes degree-of-freedom constraints. - APDL Command: DDELE + Mechanical APDL Command: `DDELE `_ Parameters ---------- - node - Node for which constraint is to be deleted. If ALL, NEND and NINC - are ignored and constraints for all selected nodes [NSEL] are - deleted. If NODE = P, graphical picking is enabled and all - remaining command fields are ignored (valid only in the GUI). A - component name may also be substituted for NODE. - - lab - Valid degree of freedom label. If ALL, use all selected labels - [DOFSEL]. Structural labels: UX, UY, or UZ (displacements); ROTX, - ROTY, or ROTZ (rotations); WARP (warping). Thermal labels: TEMP, - TBOT, TE2, TE3, . . ., TTOP (temperature). Acoustic labels: PRES - (pressure); UX, UY, or UZ (displacements for FSI coupled elements). - Electric label: VOLT (voltage). Magnetic labels: MAG (scalar - magnetic potential); AX, AY, or AZ (vector magnetic potentials). - Diffusion label: CONC (concentration). - - nend, ninc - Delete constraints from NODE to NEND (defaults to NODE) in steps of - NINC (defaults to 1). - - rkey - Ramping key: - - OFF - Loads are step-removed (default). - - ON or FORCE - Forces on the specified degrees of freedom (Lab) are ramped during the next - load step. The forces are ramped from the reaction - forces of the previous load step, regardless of - whether or not a constraint was present. If the - specified node(s) and degree(s) of freedom has a - force value currently defined, the force is ramped - from the reaction force value to the currently - applied force value. If no force is currently - applied, the force is ramped from the reaction force - value to zero. + node : str + Node for which constraint is to be deleted. If ALL, ``NEND`` and ``NINC`` are ignored and + constraints for all selected nodes ( :ref:`nsel` ) are deleted. If ``NODE`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``NODE``. + + lab : str + Valid degree of freedom label. If ALL, use all selected labels ( :ref:`dofsel` ). Structural + labels: UX, UY, or UZ (displacements); ROTX, ROTY, or ROTZ (rotations); WARP (warping). Thermal + labels: TEMP, TBOT, TE2, TE3,..., TTOP (temperature). Acoustic labels: PRES (pressure); UX, UY, + or UZ (displacements for FSI coupled elements). Electric label: VOLT (voltage). Magnetic labels: + MAG (scalar magnetic potential); AZ (vector magnetic potential). Diffusion label: CONC + (concentration). + + In structural analyses, the following velocity and acceleration load labels are also valid: + VELX, VELY, VELZ (translational velocities); OMGX, OMGY, OMGZ (rotational velocities); ACCX, + ACCY, ACCZ (translational accelerations); DMGX, DMGY, DMGZ (rotational accelerations). + + In structural analyses, HDSP (hydrostatic pressure) is also valid. + + If the node is connected to an ``ELBOW290`` element, the following pipe cross-section degree of + freedom labels are also valid: SE, SO, SW, SRA, and SRT. (For details, see the ``ELBOW290`` + documentation.) The degrees of freedom are not included when ``Lab`` = ALL. To constrain all + cross- section degrees of freedom, specify ``Lab`` = SECT. + + nend : str + Delete constraints from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` + (defaults to 1). + + ninc : str + Delete constraints from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` + (defaults to 1). + + rkey : str + Ramping option: + + * ``OFF`` - Loads are step-removed (default). + + * ``ON or FORCE`` - Forces on the specified degrees of freedom ( ``Lab`` ) are ramped during the + next load step. The forces are ramped from the reaction forces of the previous load step, regardless + of whether or not a constraint was present. If the specified node(s) and degree(s) of freedom has a + force value currently defined, the force is ramped from the reaction force value to the currently + applied force value. If no force is currently applied, the force is ramped from the reaction force + value to zero. The ramping behavior is not in effect if the subsequent force is applied in tabular + format. + + For degrees of freedom other than structural and TEMP, UX, UY, YZ, ROTX, ROTY, and ROTZ + + when performing a restart at an intermediate point during a load step, Not at the beginning or end + of a load step. + + the reaction-force data is not available. Therefore, the force is ramped from zero to the currently + applied force value (if it exists) for the specified node(s) and degree(s) of freedom. + + For structural and TEMP degrees of freedom, during a restart from an intermediate point during a + load step, the reaction-force data is available. Therefore, it is ramped down during this restart + step if no other loads are applied. See :ref:`DDELE_notes` for more information about the behavior + of this option. Notes ----- - Deleting a constraint is not the same as setting it to zero (which - "fixes" the degree of freedom to a zero value). Deleting a constraint - has the same effect as deactivating, releasing, or setting the - constraint "free." The node and the degree of freedom label must be - selected [NSEL, DOFSEL]. + + .. _DDELE_notes: + + Deleting a constraint is not the same as setting it to zero (which fixes the degree of freedom to a + zero value). Deleting a constraint has the same effect as deactivating, releasing, or setting the + constraint free. The node and the degree of freedom label must be selected ( :ref:`nsel`, + :ref:`dofsel` ). + + For structural degrees of freedom, the following limitation exists when the analysis is restarted: + + * If a new force is applied ( :ref:`f` ) upon restart of the load step during which :ref:`ddele`, + ``NODE``, ``DofLabel``,,,RFORCE (or ON) was issued, the force will show a jump to the current + value at the time of restart before being ramped to its final value. + + Upon restart, it is good practice is to allow the reaction force to ramp down to zero in a load + step, then to apply new loads in the next load step. This command is also valid in PREP7. """ command = f"DDELE,{node},{lab},{nend},{ninc},{rkey}" return self.run(command, **kwargs) - def dflx(self, node="", bx="", by="", bz="", bx2="", by2="", bz2="", **kwargs): - """Imposes a uniform magnetic flux B on an edge-element electromagnetic + def dflx( + self, + node: str = "", + bx: str = "", + by: str = "", + bz: str = "", + bx2: str = "", + by2: str = "", + bz2: str = "", + **kwargs, + ): + r"""Imposes a uniform magnetic flux B on an edge-element electromagnetic model. - APDL Command: DFLX - model. + Mechanical APDL Command: `DFLX `_ Parameters ---------- - node - Nodes at which the edge-flux (AZ) constraints corresponding to the - uniform magnetic flux are to be specified. Valid options are ALL - (default) or Component Name. If ALL, constraints are applied to all - selected nodes (NSEL). + node : str + Nodes at which the edge-flux (AZ) constraints corresponding to the uniform magnetic flux are to + be specified. Valid options are ALL (default) or Component Name. If ALL, constraints are applied + to all selected nodes ( :ref:`nsel` ). - bx, by, bz + bx : str Real components of magnetic flux B. - bx2, by2, bz2 + by : str + Real components of magnetic flux B. + + bz : str + Real components of magnetic flux B. + + bx2 : str + Imaginary components of magnetic flux B. + + by2 : str + Imaginary components of magnetic flux B. + + bz2 : str Imaginary components of magnetic flux B. Notes ----- - The DFLX command sets the constraints on the edge-flux (AZ) degrees of - freedom to produce a uniform magnetic flux B in an edge-based - electromagnetic analysis using elements SOLID236 and SOLID237. The - command ignores the corner nodes of the elements (even if they were - selected) and imposes the AZ-constraints on the mid-side nodes only. - The AZ-constraints are imposed in the active Cartesian coordinate - system. A non-Cartesian coordinate system will be ignored by the DFLX - command. - The edge-flux constraints at the mid-side nodes are derived from the - magnetic vector potential A, which is related to the imposed magnetic - flux B as follows: + .. _DFLX_notes: + + The :ref:`dflx` command sets the constraints on the edge-flux (AZ) degrees of freedom to produce a + uniform magnetic flux B in an edge-based electromagnetic analysis using one of these element types: + ``SOLID226``, ``SOLID227``, ``SOLID236``, or ``SOLID237``. The command ignores the corner nodes of + the elements (even if they were selected) and imposes the AZ-constraints on the mid-side nodes only. + The AZ-constraints are imposed in the active Cartesian coordinate system. A non-Cartesian coordinate + system will be ignored by the :ref:`dflx` command. + + The edge-flux constraints at the mid-side nodes are derived from the magnetic vector potential + **A**, which is related to the imposed magnetic flux **B** as follows: - where r is the position of the mid-side node. + .. math:: - The DFLX command creates a component named _DFLX for the constrained - midside nodes. You can use this component to delete the constraints - imposed by the DFLX command. + equation not available + + where **r** is the position of the mid-side node. + + The :ref:`dflx` command creates a component named _DFLX for the constrained midside nodes. You can + use this component to delete the constraints imposed by the :ref:`dflx` command. This command is also valid in PREP7. """ command = f"DFLX,{node},{bx},{by},{bz},{bx2},{by2},{bz2}" return self.run(command, **kwargs) - def dj(self, elem="", label="", value="", **kwargs): - """Specifies boundary conditions on the components of relative motion of a + def dj(self, elem: str = "", label: str = "", value: str = "", **kwargs): + r"""Specifies boundary conditions on the components of relative motion of a joint element. - APDL Command: DJ - joint element. + Mechanical APDL Command: `DJ `_ Parameters ---------- - elem + elem : str Element number or ALL to be specified. - label + label : str Valid labels are: - UX - Displacement in local x direction. + * ``UX`` - Displacement in local x direction. - UY - Displacement in local y direction. + * ``UY`` - Displacement in local y direction. - UZ - Displacement in local z direction. + * ``UZ`` - Displacement in local z direction. - ROTX - Rotation about local x axis. + * ``ROTX`` - Rotation about local x axis. - ROTY - Rotation about local y axis. + * ``ROTY`` - Rotation about local y axis. - ROTZ - Rotation about local y axis. + * ``ROTZ`` - Rotation about local y axis. - VELX - Linear velocity in local x direction. + * ``VELX`` - Linear velocity in local x direction. - VELY - Linear velocity in local y direction. + * ``VELY`` - Linear velocity in local y direction. - VELZ - Linear velocity in local z direction. + * ``VELZ`` - Linear velocity in local z direction. - OMGX - Angular velocity in local x direction. + * ``OMGX`` - Angular velocity in local x direction. - OMGY - Angular velocity in local y direction. + * ``OMGY`` - Angular velocity in local y direction. - OMGZ - Angular velocity in local z direction. + * ``OMGZ`` - Angular velocity in local z direction. - ACCX - Linear acceleration in local x direction. + * ``ACCX`` - Linear acceleration in local x direction. - ACCY - Linear acceleration in local y direction. + * ``ACCY`` - Linear acceleration in local y direction. - ACCZ - Linear acceleration in local z direction. + * ``ACCZ`` - Linear acceleration in local z direction. - DMGX - Angular acceleration in local x direction. + * ``DMGX`` - Angular acceleration in local x direction. - DMGY - Angular acceleration in local y direction. + * ``DMGY`` - Angular acceleration in local y direction. - DMGZ - Angular acceleration in local z direction. + * ``DMGZ`` - Angular acceleration in local z direction. - value + value : str Value of the label. Notes ----- - This command is valid for MPC184 joint elements. See DJDELE for - information on deleting boundary conditions applied with the DJ - command. - You can apply only one displacement, velocity, or acceleration load at - any relative degree of freedom. If multiple loads are specified, the - last applied load overrides the previous ones. For example, the - following commands apply loads to element 100: + .. _DJ_notes: - In this case, the velocity load (VELX) applied in the last command will - override the displacement load (UX). + This command is valid for ``MPC184`` joint elements. See :ref:`djdele` for information about + deleting boundary conditions applied via this command. - Tabular boundary conditions (VALUE = %tabname%) can be used. + You can apply only one displacement, velocity, or acceleration load at any relative degree of + freedom. If multiple loads are specified, the last applied load overrides the previous ones. For + example, the following commands apply loads to element 100: - %_FIX% is an ANSYS reserved table name. When VALUE is set to %_FIX%, - ANSYS will prescribe the degree of freedom to the "current" relative - displacement value. This option is only valid for the following labels: - UX, UY, UZ, ROTX, ROTY, ROTZ. In most cases, %_FIX% usage is efficient - and recommended for all structural degrees of freedom. + * D,100,UX, ``Value`` + * D,100,VELX, ``Value`` + + In this case, the velocity load (VELX) applied in the last command will override the displacement + load (UX). + + Tabular boundary conditions ( ``VALUE`` = ``tabname``) can be used. + + %_FIX% is a Mechanical APDL reserved table name. When ``VALUE`` is set to %_FIX%, the program + sprescribe + the degree of freedom to the current relative displacement value. This option is only valid for the + following labels: UX, UY, UZ, ROTX, ROTY, ROTZ. In most cases, %_FIX% usage is efficient and + recommended for all structural degrees of freedom. + + In a modal analysis, the values of the eigenvectors at the degree of freedom connected via :ref:`dj` + may be insufficiently accurate to satisfy the :ref:`dj` constraint conditions. """ command = f"DJ,{elem},{label},{value}" return self.run(command, **kwargs) - def djdele(self, elem="", lab="", **kwargs): - """Deletes boundary conditions on the components of relative motion of a + def djdele(self, elem: str = "", lab: str = "", **kwargs): + r"""Deletes boundary conditions on the components of relative motion of a joint element. - APDL Command: DJDELE - joint element. + Mechanical APDL Command: `DJDELE `_ Parameters ---------- - elem - Element number or ALL. ALL (or leaving this field blank) will - delete all joint element boundary conditions specified by LAB. + elem : str + Element number or ALL. ALL (or leaving this field blank) will delete all joint element boundary + conditions specified by ``LAB``. - lab + lab : str Valid labels are: - UX - Displacement in local x direction. + * ``UX`` - Displacement in local x direction. - UY - Displacement in local y direction. + * ``UY`` - Displacement in local y direction. - UZ - Displacement in local z direction. + * ``UZ`` - Displacement in local z direction. - ROTX - Rotation about local x axis. + * ``ROTX`` - Rotation about local x axis. - ROTY - Rotation about local y axis. + * ``ROTY`` - Rotation about local y axis. - ROTZ - Rotation about local z axis. + * ``ROTZ`` - Rotation about local z axis. - VELX - Linear velocity in local x direction. + * ``VELX`` - Linear velocity in local x direction. - VELY - Linear velocity in local y direction. + * ``VELY`` - Linear velocity in local y direction. - VELZ - Linear velocity in local z direction. + * ``VELZ`` - Linear velocity in local z direction. - OMGX - Angular velocity in local x direction. + * ``OMGX`` - Angular velocity in local x direction. - OMGY - Angular velocity in local y direction. + * ``OMGY`` - Angular velocity in local y direction. - OMGZ - Angular velocity in local z direction. + * ``OMGZ`` - Angular velocity in local z direction. - ACCX - Linear acceleration in local x direction. + * ``ACCX`` - Linear acceleration in local x direction. - ACCY - Linear acceleration in local y direction. + * ``ACCY`` - Linear acceleration in local y direction. - ACCZ - Linear acceleration in local z direction. + * ``ACCZ`` - Linear acceleration in local z direction. - DMGX - Angular acceleration in local x direction. + * ``DMGX`` - Angular acceleration in local x direction. - DMGY - Angular acceleration in local y direction. + * ``DMGY`` - Angular acceleration in local y direction. - DMGZ - Angular acceleration in local z direction. + * ``DMGZ`` - Angular acceleration in local z direction. - ALL, or (blank) - Delete all applied boundary conditions. + * ``ALL, or (blank)`` - Delete all applied boundary conditions. Notes ----- - This command is valid for MPC184 joint elements. See DJ for information - on specifying boundary conditions on the components of relative motion - of a joint element. + + .. _DJDELE_notes: + + This command is valid for ``MPC184`` joint elements. See :ref:`dj` for information on + specifying boundary conditions on the components of relative motion of a joint element. """ command = f"DJDELE,{elem},{lab}" return self.run(command, **kwargs) - def djlist(self, elem="", **kwargs): - """Lists boundary conditions applied to joint elements. + def djlist(self, elem: str = "", **kwargs): + r"""Lists boundary conditions applied to joint elements. - APDL Command: DJLIST + Mechanical APDL Command: `DJLIST `_ Parameters ---------- - elem - Element number or ALL (or blank). Lists joint element boundary - conditions on the specified element(s). + elem : str + Element number or ALL (or blank). Lists joint element boundary conditions on the specified + element(s). Notes ----- - This command is valid for MPC184 joint elements. See DJ for information - on specifying boundary conditions on joint elements. + + .. _DJLIST_notes: + + This command is valid for ``MPC184`` joint elements. See :ref:`dj` for information on specifying + boundary conditions on joint elements. """ command = f"DJLIST,{elem}" return self.run(command, **kwargs) - def dlist(self, node1="", node2="", ninc="", **kwargs): - """Lists DOF constraints. + def dlist(self, node1: str = "", node2: str = "", ninc: str = "", **kwargs): + r"""Lists DOF constraints. - APDL Command: DLIST + Mechanical APDL Command: `DLIST `_ Parameters ---------- - node1, node2, ninc - List constraints for nodes NODE1 to NODE2 (defaults to NODE1) in - steps of NINC (defaults to 1). If ALL (default), NODE2 and NINC - are ignored and constraints for all selected nodes [NSEL] are - listed. If NODE1 = 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 NODE1(NODE2 and NINC are - ignored). + node1 : str + List constraints for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL (default), ``NODE2`` and ``NINC`` are ignored and constraints for all + selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + node2 : str + List constraints for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL (default), ``NODE2`` and ``NINC`` are ignored and constraints for all + selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + ninc : str + List constraints for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL (default), ``NODE2`` and ``NINC`` are ignored and constraints for all + selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). Notes ----- - Listing applies to the selected nodes [NSEL] and the selected degree of - freedom labels [DOFSEL]. + + .. _DLIST_notes: + + Listing applies to the selected nodes ( :ref:`nsel` ) and the selected degree of freedom labels ( + :ref:`dofsel` ). This command is valid in any processor. """ command = f"DLIST,{node1},{node2},{ninc}" return self.run(command, **kwargs) - def dscale(self, rfact="", ifact="", tbase="", **kwargs): - """Scales DOF constraint values. + def dscale(self, rfact: str = "", ifact: str = "", tbase: str = "", **kwargs): + r"""Scales DOF constraint values. - APDL Command: DSCALE + Mechanical APDL Command: `DSCALE `_ Parameters ---------- - rfact - Scale factor for the real component. Zero (or blank) defaults to - 1.0. Use a small number for a zero scale factor. + rfact : str + Scale factor for the real component. Zero (or blank) defaults to 1.0. Use a sma ll number + for a zero scale factor. - ifact - Scale factor for the imaginary component. Zero (or blank) defaults - to 1.0. Use a small number for a zero scale factor. + ifact : str + Scale factor for the imaginary component. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. - tbase - Base temperature for temperature difference. For temperatures, the - scale factor is applied to the temperature difference (T-TBASE) and - then added to TBASE. T is the current temperature. + tbase : str + Base temperature for temperature difference. For temperatures, the scale factor is applied to + the temperature difference ( ``T`` - ``TBASE`` ) and then added to ``TBASE``. ``T`` is the + current temperature. Notes ----- - Scales degree of freedom constraint values (displacement, temperature, - etc.) in the database. If velocity and acceleration boundary - conditions are applied in a structural analysis, they are also scaled - by this command. Solid model boundary conditions are not scaled by this - command, but boundary conditions on the FE model are scaled. - Note:: : Such scaled FE boundary conditions may still be overwritten by - unscaled solid model boundary conditions if a subsequent boundary - condition transfer occurs. + .. _DSCALE_notes: + + Scales degree of freedom constraint values (displacement, temperature, etc.) in the database. If + velocity and acceleration boundary conditions are applied in a structural analysis, they are also + scaled by this command. Solid model boundary conditions are not scaled by this command, but boundary + conditions on the FE model are scaled. Such scaled FE boundary conditions may still be overwritten + by unscaled solid model boundary conditions if a subsequent boundary condition transfer occurs. - Scaling applies to the previously defined values for the selected nodes - [NSEL] and the selected degree of freedom labels [DOFSEL]. Issue DLIST - command to review results. + Scaling applies to the previously defined values for the selected nodes ( :ref:`nsel` ) and the + selected degree of freedom labels ( :ref:`dofsel` ). Issue :ref:`dlist` command to review results. - DSCALE does not work for tabular boundary conditions. + :ref:`dscale` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"DSCALE,{rfact},{ifact},{tbase}" return self.run(command, **kwargs) - def dsym(self, lab="", normal="", kcn="", **kwargs): - """Specifies symmetry or antisymmetry degree-of-freedom constraints on + def dsym(self, lab: str = "", normal: str = "", kcn: str = "", **kwargs): + r"""Specifies symmetry or antisymmetry degree-of-freedom constraints on nodes. - APDL Command: DSYM - nodes. + Mechanical APDL Command: `DSYM `_ Parameters ---------- - lab + lab : str Symmetry label: - SYMM - Generate symmetry constraints as described below (default). + * ``SYMM`` - Generate symmetry constraints as described below (default). - ASYM - Generate antisymmetry constraints as described below. + * ``ASYM`` - Generate antisymmetry constraints as described below. - normal - Surface orientation label to determine the constraint set (surface - is assumed to be perpendicular to this coordinate direction in - coordinate system KCN): + normal : str + Surface orientation label to determine the constraint set (surface is assumed to be perpendicular to + this coordinate direction in coordinate system ``KCN`` ): - X - Surface is normal to coordinate X direction (default). Interpreted as R - direction for non-Cartesian coordinate systems. + * ``X`` - Surface is normal to coordinate X direction (default). Interpreted as R direction for non- + Cartesian coordinate systems. - Y - Surface is normal to coordinate Y direction. θ direction for non-Cartesian - coordinate systems. + * ``Y`` - Surface is normal to coordinate Y direction. θ direction for non-Cartesian + coordinate systems. - Z - Surface is normal to coordinate Z direction. Φ direction for spherical or - toroidal coordinate systems. + * ``Z`` - Surface is normal to coordinate Z direction. Φ direction for spherical or toroidal + coordinate systems. - kcn - Reference number of global or local coordinate system used to - define surface orientation. + kcn : str + Reference number of global or local coordinate system used to define surface orientation. Notes ----- - Specifies symmetry or antisymmetry degree-of-freedom constraints on the - selected nodes. The nodes are first automatically rotated (any - previously defined rotations on these nodes are redefined) into - coordinate system KCN, then zero-valued constraints are generated, as - described below, on the selected degree-of-freedom set (limited to - displacement, velocity, and magnetic degrees of freedom) [DOFSEL]. - Constraints are defined in the (rotated) nodal coordinate system, as - usual. See the D and NROTAT commands for additional details about - constraints and nodal rotations. + + .. _DSYM_notes: + + Specifies symmetry or antisymmetry degree-of-freedom constraints on the selected nodes. The nodes + are first automatically rotated (any previously defined rotations on these nodes are redefined) into + coordinate system ``KCN``, then zero-valued constraints are generated, as described below, on the + selected degree-of-freedom set (limited to displacement, velocity, and magnetic degrees of freedom) + ( :ref:`dofsel` ). Constraints are defined in the (rotated) nodal coordinate system, as usual. See + the :ref:`d` and :ref:`nrotat` commands for additional details about constraints and nodal + rotations. This command is also valid in PREP7. - Symmetry or antisymmetry constraint generations are based upon the - valid degrees of freedom in the model, i.e., the degrees of freedom - associated with the elements attached to the nodes. The labels for - degrees of freedom used in the generation depend on the Normal label. + .. _DSYM_extranote1: + + Symmetry or antisymmetry constraint generations are based upon the valid degrees of freedom in the + model, that is, the de grees of freedom associated with the elements attached to the nodes. + The labels for degrees of freedom used in the generation depend on the ``Normal`` label. For displacement degrees of freedom, the constraints generated are: + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + For velocity degrees of freedom, the constraints generated are: - For magnetic degrees of freedom, the SYMM label generates flux normal - conditions (flux flows normal to the surface). Where no constraints - are generated, the flux normal condition is "naturally" satisfied. The - ASYM label generates flux parallel conditions (flux flows parallel to + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + For the 2D vector magnetic degree of freedom, AZ, symmetry is naturally satisfied and the SYMM label + generates no constraints. The ASYM label generates flux parallel conditions (flux flows parallel to the surface). + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. """ command = f"DSYM,{lab},{normal},{kcn}" return self.run(command, **kwargs) - def dval(self, baseid="", lab="", value="", value2="", keycal="", **kwargs): - """Defines values at enforced motion base. + def dval( + self, + baseid: str = "", + lab: str = "", + value: str = "", + value2: str = "", + keycal: str = "", + **kwargs, + ): + r"""Defines values at enforced motion base. - APDL Command: DVAL + Mechanical APDL Command: `DVAL `_ Parameters ---------- - baseid - The identification number of the enforced motion base (defined - using the D command in the modal analysis). - - lab - U + baseid : str + The identification number of the enforced motion base (defined using the :ref:`d` command in the + modal analysis). - U - Enforced displacement. + lab : str + * ``U`` - Enforced displacement. - ACC - Enforced acceleration. + * ``ACC`` - Enforced acceleration. - value - The value or table name reference for tabular boundary conditions. - To specify a table, enclose the table name in percent (%) signs - (DVAL,BaseID,U,%tablename%). Use the ``*DIM`` command to define a - table. + value : str + The value or table name reference for tabular boundary conditions. To specify a table, enclose + the table name in percent (%) signs ( :ref:`dval`, ``BaseID``,U,``tablename``). Use the + :ref:`dim` command to define a table. - value2 - The value of the second degree of freedom (if present). If the - analysis type and the degree of freedom allow a complex input, - VALUE is the real component and VALUE2 is the imaginary component. + value2 : str + The value of the second degree of freedom (if present). If the analysis type and the degree of + freedom allow a complex input, ``VALUE`` is the real component and ``VALUE2`` is the imaginary + component. - keycal + keycal : str Displacement result calculation key: - ON - Calculate absolute displacement and acceleration results (default). + * ``ON`` - Calculate absolute displacement and acceleration results (default). - OFF - Calculate relative displacement and acceleration results. + * ``OFF`` - Calculate relative displacement and acceleration results. Notes ----- - In a mode-superposition harmonic or transient analysis, you can apply - enforced displacement or acceleration loads. If multiple loads are - specified for the same base identification number (BaseID), the last - load applied overrides the previous ones. For example, the following - commands apply displacement to the base with identification number 1: - In this case, the acceleration (ACC) applied in the last command will - override the displacement (U). + .. _DVAL_notes: + + In a mode-superposition harmonic or transient analysis, you can apply enforced displacement or + acceleration loads. If multiple loads are specified for the same base identification number + (BaseID), the last load applied overrides the previous ones. For example, the following commands + apply displacement to the base with identification number 1: + + .. code:: apdl + + DVAL,1,U,VALUE + DVAL,1,ACC,VALUE + + In this case, the acceleration (ACC) applied in the last command will override the displacement (U). - Issue LSCLEAR,LSOPT to delete DVAL command options from the database. + Issue :ref:`lsclear`,LSOPT to delete :ref:`dval` command options from the database. - For more information, see Enforced Motion Method for Mode-Superposition - Transient and Harmonic Analyses in the Structural Analysis Guide and - Enforced Motion Method for Transient and Harmonic Analyses in the - Mechanical APDL Theory Reference. + For more information, see `Enforced Motion Method for Mode-Superposition Transient and Harmonic + Analyses `_ + `Enforced Motion Method for Transient and Harmonic Analyses + `_ """ command = f"DVAL,{baseid},{lab},{value},{value2},{keycal}" return self.run(command, **kwargs) def gsbdata( self, - labz="", - valuez="", - labx="", - valuex="", - laby="", - valuey="", + labz: str = "", + valuez: str = "", + labx: str = "", + valuex: str = "", + laby: str = "", + valuey: str = "", **kwargs, ): - """Specifies the constraints or applies the load at the ending point for + r"""Specifies the constraints or applies the load at the ending point for generalized plane strain + option. - APDL Command: GSBDATA - generalized plane strain option. + Mechanical APDL Command: `GSBDATA `_ Parameters ---------- - labz + labz : str Constraint or load at the ending point in the fiber Z direction. - F - Apply a force in the fiber direction (default). + * ``F`` - Apply a force in the fiber direction (default). - LFIBER - Define a length change in the fiber direction. + * ``LFIBER`` - Define a length change in the fiber direction. - valuez - Value for LabZ. The default is zero. + valuez : str + Value for ``LabZ``. The default is zero. - labx + labx : str Constraint or load on rotation about X. - MX - Supply a moment to cause the rotation of the ending plane about X (default). + * ``MX`` - Supply a moment to cause the rotation of the ending plane about X (default). - ROTX - Define a rotation angle (in radians) of the ending plane about X. + * ``ROTX`` - Define a rotation angle (in radians) of the ending plane about X. - valuex - Value for LabX. The default is zero. + valuex : str + Value for ``LabX``. The default is zero. - laby + laby : str Constraint or load on rotation about Y - MY - Supply a moment to cause the rotation of the ending plane about Y (default). + * ``MY`` - Supply a moment to cause the rotation of the ending plane about Y (default). - ROTY - Define a rotation angle (in radians) of the ending plane about Y. + * ``ROTY`` - Define a rotation angle (in radians) of the ending plane about Y. - valuey - Value for LabY. The default is zero. + valuey : str + Value for ``LabY``. The default is zero. Notes ----- - All inputs are in the global Cartesian coordinate system. For more - information about the generalized plane strain feature, see Generalized - Plane Strain Option of Current-Technology Solid Elements in the Element - Reference. + + .. _GSBDATA_notes: + + All inputs are in the global Cartesian coordinate system. For more information about the generalized + plane strain feature, see Generalized Plane Strain Option of Current-Technology Solid Elements in + the `Element Reference + `_. This command is also valid in PREP7. """ command = f"GSBDATA,{labz},{valuez},{labx},{valuex},{laby},{valuey}" return self.run(command, **kwargs) - def gslist(self, lab="", **kwargs): - """When using generalized plane strain, lists the input data or solutions. + def gslist(self, lab: str = "", **kwargs): + r"""When using generalized plane strain, lists the input data or solutions. - APDL Command: GSLIST + Mechanical APDL Command: `GSLIST `_ Parameters ---------- - lab + lab : str Specify the content to be listed. - GEOMETRY - List the data input using GSGDATA + * ``GEOMETRY`` - List the data input using GSGDATA + + * ``BC`` - List the data input using GSBDATA. - BC - List the data input using GSBDATA. + * ``REACTIONS`` - When the command is issued in POST1, list the reaction force at the ending point, - REACTIONS - When the command is issued in POST1, list the reaction force at the ending - point, + and the moment about X and Y if the corresponding constraints were applied. - and the moment about X and Y if the corresponding constraints were applied. - RESULTS + * ``RESULTS`` - When the command is issued in POST1, list the change of fiber length at the ending + point during deformation and the rotation of the ending plane about X and Y during deformation. - When the command is issued in POST1, list the change of fiber length at the ending point during deformation and the rotation of the ending plane about X and Y during deformation. - ALL + * ``ALL`` - List all of the above (default). Notes ----- - This command can be used to list the initial position of the ending - plane, the applied load or displacements in the fiber direction, the - resulting position of the ending plane after deformation, and the - available reaction forces and moments at the ending point. - All inputs and outputs are in the global Cartesian coordinate system. - For more information about the generalized plane strain feature, see - Generalized Plane Strain Option of Current-Technology Solid Elements in - the Element Reference. + .. _GSLIST_notes: + + This command can be used to list the initial position of the ending plane, the applied load or + displacements in the fiber direction, the resulting position of the ending plane after deformation, + and the available reaction forces and moments at the ending point. + + All inputs and outputs are in the global Cartesian coordinate system. For more information about the + generalized plane strain feature, see Generalized Plane Strain Option of Current-Technology Solid + Elements in the `Element Reference + `_. This command is valid in any processor. """ command = f"GSLIST,{lab}" return self.run(command, **kwargs) + + def ldread( + self, + lab: str = "", + lstep: str = "", + sbstep: str = "", + time: str = "", + kimg: int | str = "", + fname: str = "", + ext: str = "", + **kwargs, + ): + r"""Reads results from the results file and applies them as loads. + + Mechanical APDL Command: `LDREAD `_ + + Parameters + ---------- + lab : str + Valid load label: + + * ``TEMP`` - Temperatures from a thermal analysis are applied as body force nodal loads ( :ref:`bf` + ) in a structural analysis or other type of analysis. + + When used in conjunction with ``KIMG`` = 1 or ``KIMG`` = 2, temperatures can be applied to a + subsequent thermal analysis as nodal loads ( :ref:`d` ) or initial conditions ( :ref:`ic` ), + respectively. + + See the :ref:`LDREAD_notes` section for details on transferring temperatures from layered thermal + shell elements ( ``SHELL131``, ``SHELL132`` ) and layered thermal solid elements ( ``SOLID278``, + ``SOLID279`` ). + + * ``FORC`` - Forces from an electromagnetic analysis are applied as force loads ( :ref:`f` ) in a + structural analysis. :ref:`ldread`,FORC reads coupling forces. See the discussion on `force + computation + `_ + in the `Low-Frequency Electromagnetic Analysis Guide `_. + + For a full harmonic magnetic analysis, FORC represents the time-averaged force (use in conjunction + with ``KIMG`` = 2). Values are in the nodal coordinate system for the force loads ( :ref:`f` ). + + * ``HGEN`` - Heat generations from an electromagnetic analysis are applied as body-force loads ( + :ref:`bfe` ) in a thermal analysis. For a full harmonic analysis, HGEN represents the time-averaged + heat generation load (use in conjunction with ``KIMG`` = 2). + + * ``JS`` - Source current density from a current-conduction analysis are applied as body-force loads + ( :ref:`bfe` ). Values are in the global Cartesian coordinate system. + + * ``EF`` - Electric field element centroid values from an electrostatic analysis are applied as + body-force loads ( :ref:`bfe` ) in a magnetic analysis. Values are in the global Cartesian + coordinate system. + + * ``REAC`` - Reaction loads from any analysis are applied as force loads ( :ref:`f` ) in any + analysis. Values are in the nodal coordinate system. + + * ``CONC`` - Concentrations from a diffusion analysis are applied to a subsequent diffusion analysis + as nodal loads ( :ref:`d` ) or initial conditions ( :ref:`ic` ) when used in conjunction with + ``KIMG`` =1 or ``KIMG`` =2, respectively. + + * ``VMEN`` - Mean flow velocities from a static mean flow analysis are applied to a subsequent + harmonic or modal solution of the convective wave equation as body-force loads ( :ref:`bf` ). + + * ``VOLT`` - Voltages from an electric, electrostatic, or electromagnetic analysis are applied to a + subsequent electric, electrostatic, or electromagnetic analysis as nodal loads ( :ref:`d` ) when + ``KIMG`` = 1 or as initial conditions ( :ref:`ic` ) when ``KIMG`` = 2. + + lstep : str + Load step number of the data set to be read. Defaults to 1. If LAST, ignore ``SBSTEP`` and + ``TIME`` and read the last data set. + + sbstep : str + Substep number (within ``LSTEP`` ). If zero (or blank), ``LSTEP`` represents the last substep of + the load step. + + time : str + Time-point identifying the data set to be read. Used only if both ``LSTEP`` and ``SBSTEP`` are + zero (or blank). If ``TIME`` is between two solution time points on the results file, a linear + interpolation is done between the two data sets. If ``TIME`` is beyond the last time point on + the file, use the last time point. + + kimg : int or str + When used with results from harmonic analyses ( :ref:`antype`,HARMIC) ``KIMG`` establishes which set of data to read: + + * ``0`` - Read the real part of the solution. Valid also for ``Lab`` = EHFLU to read in time-average + heat flux. + + * ``1`` - Read the imaginary part of the solution. + + * ``2`` - Calculate and read the time-average part. Meaningful for ``Lab`` = HGEN or FORC. + + When used with the PRES label, ``KIMG`` represents the shell element face on which to apply the pressure: + + * ``1`` - Apply pressure to face 1 + + * ``2`` - Apply pressure to face 2 + + When used with the TEMP label, ``KIMG`` indicates how temperatures are to be applied. + + * ``0`` - Apply temperatures as body loads ( :ref:`bf` ) + + * ``1`` - Apply temperatures as nodal loads ( :ref:`d` ) + + * ``2`` - Apply temperatures as initial conditions ( :ref:`ic` ) + + When used with the CONC label, ``KIMG`` indicates how concentrations are to be applied. + + * ``1`` - Apply concentrations as nodal loads ( :ref:`d` ) + + * ``2`` - Apply concentrations as initial conditions ( :ref:`ic` ) + + When used with the VOLT label, ``KIMG`` indicates how voltages are to be applied. + + * ``1`` - Apply voltages as nodal loads ( :ref:`d` ) + + * ``2`` - Apply voltages as initial conditions ( :ref:`ic` ) + + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. The file name defaults to :file:`Jobname`. + + ext : str + Filename extension (eight-character maximum). The extension defaults to RST (or RMF for a static + mean flow analysis) if ``Fname`` is blank. + + Notes + ----- + + .. _LDREAD_notes: + + The :ref:`ldread` command reads results data from the results file and applies them as loads. + + The command can also apply results from an analysis defined with one physics environment as loads on + a second analysis using a different physics environment. Results values are applied as loads for + field-coupling effects (for example, output temperatures from a thermal analysis as input to a + structural analysis). + + The command works based on the assumption that the meshes have not changed. + + Nodal loads are applied only to selected nodes. Element loads are applied only to selected elements. + Element surface loads are applied only to selected elements where all face nodes for that surface + are selected. + + To assure proper distribution of the surface loads, select only the nodes on the element face where + the surface load is to be applied. + + Scaling and accumulation specifications are applied as the loads are read via the following + commands: + + * :ref:`bfcum` for body-force loads. (Heat-generation loads are not accumulated.) + + * :ref:`sfcum` for surface loads. + + * :ref:`fcum` for force loads. + + List the results via the appropriate list command: + + * :ref:`bflist` or :ref:`bfelist` for body-force loads. + + * :ref:`sfelist` for surface loads. + + * :ref:`flist` for force loads. + + Values may be redefined after being read by issuing :ref:`ldread` again with a different load step + and substep, or time value. + + This command is also valid in PREP7. + + **Transferring Temperature Output from SHELL131 and SHELL132** + + If a thermal analysis uses ``SHELL131`` or ``SHELL132`` thermal shell elements, temperatures can be + transferred as body force element loads ( :ref:`bfe` ). In most cases, only the top and bottom + temperatures from ``SHELL131`` and ``SHELL132`` are used by the structural shell elements; any + interior temperatures are ignored. However, all temperatures are used by ``SHELL181`` having section + input, and ``SHELL281`` having section input; for these elements, therefore, the number of + temperature points at a node generated in the thermal model must match the number of temperature + points at a node needed by the structural model. + + When using ``SHELL131`` or ``SHELL132`` information for the :ref:`ldread` operation, all element + types should specify the same set of thermal degrees of freedom. + + **Transferring Temperature Output from SOLID278 and SOLID279** + + If a thermal analysis uses ``SOLID278`` or ``SOLID279`` thermal solid elements, the temperatures are + available either at the nodes (KEYOPT(3) = 0) or at the nodes and layers (KEYOPT(3) = 1 or 2). Under + normal circumstances, only the nodal temperatures are transferred to the structural elements. + + However, if the structural elements are layered solids (KEYOPT(3) = 1 for ``SOLSH190``, + ``SOLID185``, ``SOLID186`` ) and the thermal elements have KEYOPT(3) = 1 or 2 (layered solid) and + KEYOPT(8) = 1 (store data for all layers), then the layer temperatures are transferred to the + structural elements. If the number of layers do not match, the algorithm reverts back to nodal + temperature transfer. + + ``KIMG`` = 0 (body loads) is the only valid mode for layered temperature transfer. + + **Examples** + Thermal-Stress Example: Load Transfer Coupled-Field Analysis with One-way Coupling + + Induction Heating Example: Load Transfer Coupled-Field Analysis with Two-way Coupling + """ + command = f"LDREAD,{lab},{lstep},{sbstep},{time},{kimg},{fname},{ext}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/fe_forces.py b/src/ansys/mapdl/core/_commands/solution/fe_forces.py index 1ed9f362b2d..45e971f4716 100644 --- a/src/ansys/mapdl/core/_commands/solution/fe_forces.py +++ b/src/ansys/mapdl/core/_commands/solution/fe_forces.py @@ -22,390 +22,398 @@ class FeForces: - def f(self, node="", lab="", value="", value2="", nend="", ninc="", **kwargs): - """Specifies force loads at nodes. - APDL Command: F + def f( + self, + node: str = "", + lab: str = "", + value: str = "", + value2: str = "", + nend: str = "", + ninc: str = "", + meshflag: str = "", + **kwargs, + ): + r"""Defines force loads at nodes. + + Mechanical APDL Command: `F `_ Parameters ---------- - node - Node at which force is to be specified. If ALL, NEND and NINC are - ignored and forces are applied to all selected nodes [NSEL]. If - NODE = P, graphical picking is enabled and all remaining command - fields are ignored (valid only in the GUI). A component name may - also be substituted for NODE. - - lab - Valid force label. Structural labels: FX, FY, or FZ (forces); MX, - MY, or MZ (moments). Thermal labels: HEAT, HBOT, HE2, HE3, . . ., - HTOP (heat flow). Fluid labels: FLOW (fluid flow). Electric - labels: AMPS (current flow), CHRG (electric charge). Magnetic - labels: FLUX (magnetic flux); CSGX, CSGY, or CSGZ (magnetic - current segments). Diffusion labels: RATE (diffusion flow rate). - - value - Force value or table name reference for specifying tabular boundary - conditions. To specify a table, enclose the table name in percent - signs (%), e.g., F, NODE,HEAT,%tabname%). Use the ``*DIM`` command to - define a table. - - value2 - Second force value (if any). If the analysis type and the force - allow a complex input, VALUE (above) is the real component and - VALUE2 is the imaginary component. - - nend, ninc - Specifies the same values of force at the nodes ranging from NODE - to NEND (defaults to NODE), in steps of NINC (defaults to 1). + node : str + Node at which force is to be specified. If ALL, ``NEND`` and ``NINC`` are ignored and forces are + applied to all selected nodes ( :ref:`nsel` ). If ``Node`` = P, graphical picking is enabled and + all remaining command fields are ignored (valid only in the GUI). A component name may also be + substituted for ``Node``. + + lab : str + Valid force labels are: + + * **Structural labels** : FX, FY, or FZ (forces); MX, MY, or MZ (moments). + * **Thermal labels** : HEAT, HBOT, HE2, HE3,..., HTOP (heat flow). + * **Fluid label** : FLOW (fluid flow). + * **Electric labels** : AMPS (current flow), CHRG (electric charge). + * **Magnetic labels** : FLUX (magnetic flux); CSGZ (magnetic current segment). + * **Diffusion label** : RATE (diffusion flow rate). + * **Viscous-thermal acoustics labels** : FX, FY, FZ ( `volumetric force density + `_ ). + + For structural analyses, DVOL (fluid mass flow rate) is also a valid label. See :ref:`Notes for more + information. ` + + value : str + Force value or table name reference for specifying tabular boundary conditions. To specify a + table, enclose the table name in percent signs (%), for example, :ref:`f`, + ``Node``,HEAT,``tabname``). To define a table, issue :ref:`dim`. + + value2 : str + Second force value (if any). If the analysis type and the force allow a complex input, ``VALUE`` + (above) is the real component and ``VALUE2`` is the imaginary component. + + nend : str + Specifies the same values of force at the nodes ranging from ``Node`` to ``NEND`` (defaults to + ``Node`` ), in steps of ``NINC`` (defaults to 1). + + ninc : str + Specifies the same values of force at the nodes ranging from ``Node`` to ``NEND`` (defaults to + ``Node`` ), in steps of ``NINC`` (defaults to 1). + + meshflag : str + Specifies how to apply nodal force on the mesh. Valid in a `nonlinear adaptivity analysis + `_ when ``Lab`` = + FX / FY / FZ and ``Node`` is not a component name. Not valid when ``Lab`` = ALL. + + * 0 - Nodal-force loading occurs on the current mesh (default). + * 1 - Nodal-force loading occurs on the initial mesh for nonlinear adaptivity. ( ``NEND`` and + ``NINC`` are not valid.) Notes ----- - The available force loads per node correspond to the degrees of freedom - listed under "Degrees of Freedom" in the input table for each element - type in the Element Reference. If both a force and a constrained - degree of freedom [D] are specified at the same node, the constraint - takes precedence. Forces are defined in the nodal coordinate system. - The positive directions of structural forces and moments are along and - about the positive nodal axis directions. The node and the degree of - freedom label corresponding to the force must be selected [NSEL, - DOFSEL]. - - For hydrostatic fluid elements (HSFLD241 and HSFLD242), DVOL is used to - specify fluid mass flow rate (with units of mass/time) at the pressure - node. This allows fluid to be added or taken out of the fluid elements - sharing the pressure node. A fluid density must also be specified (via - the MP command or TB command) to apply a volume change corresponding to - the prescribed fluid mass flow rate. - - Tabular boundary conditions (VALUE = %tabname%) are available only for - the following labels: Fluid (FLOW), Electric (AMPS), Structural force - (FX, FY, FZ, MX, MY, MZ), and Thermal (HEAT, HBOT, HE2, HE3, . . ., - HTOP). Tabular boundary conditions are valid only in static - (ANTYPE,STATIC), full transient (ANTYPE,TRANS), full harmonic (ANTYPE, - HARMIC), modal superposition harmonic and modal superposition transient - analyses. + + .. _F_notes: + + The available force loads per node correspond to the degrees of freedom listed under **Degrees of + Freedom** in the input table for each element type in the `Element Reference + `_. If both a + force and a constrained degree + of freedom ( :ref:`d` ) are specified at the same node, the constraint takes precedence. Forces are + defined in the nodal coordinate system. The positive directions of structural forces and moments are + along and about the positive nodal axis directions. The node and the degree-of-freedom label + corresponding to the force must be selected ( :ref:`nsel`, :ref:`dofsel` ). + + Fluid flow (FLOW) is positive when flow is out of the nodes, and negative when flow is into the + nodes. + + For hydrostatic fluid elements ( ``HSFLD241`` and ``HSFLD242`` ), DVOL is used to specify fluid mass + flow rate (with units of mass/time) at the pressure node. This allows fluid to be added or taken out + of the fluid elements sharing the pressure node. A fluid density must also be specified ( :ref:`mp` + or :ref:`tb` ) to apply a volume change corresponding to the prescribed fluid mass flow rate. + + Tabular boundary conditions ( ``VALUE`` = ``tabname``) are available only for the following labels: + Fluid (FLOW), Electric (AMPS), Structural force (FX, FY, FZ, MX, MY, MZ), Thermal (HEAT, HBOT, HE2, + HE3,..., HTOP), Diffusion (RATE). Tabular boundary conditions are valid only in static ( + :ref:`antype`,STATIC), full transient ( :ref:`antype`,TRANS), full harmonic ( :ref:`antype`, + HARMIC), modal superposition harmonic and modal superposition transient analyses. This command is also valid in PREP7. """ - command = f"F,{node},{lab},{value},{value2},{nend},{ninc}" + command = f"F,{node},{lab},{value},{value2},{nend},{ninc},,,{meshflag}" return self.run(command, **kwargs) - def fcum(self, oper="", rfact="", ifact="", **kwargs): - """Specifies that force loads are to be accumulated. + def fcum(self, oper: str = "", rfact: str = "", ifact: str = "", **kwargs): + r"""Specifies that force loads are to be accumulated. - APDL Command: FCUM + Mechanical APDL Command: `FCUM `_ Parameters ---------- - oper + oper : str Accumulation key: - REPL - Subsequent values replace the previous values (default). + * ``REPL`` - Subsequent values replace the previous values (default). - ADD - Subsequent values are added to the previous values. + * ``ADD`` - Subsequent values are added to the previous values. - IGNO - Subsequent values are ignored. + * ``IGNO`` - Subsequent values are ignored. - rfact - Scale factor for the real component. Zero (or blank) defaults to - 1.0. Use a small number for a zero scale factor. + rfact : str + Scale factor for the real component. Zero (or blank) defaults to 1.0. Use a small number for a + zero scale factor. - ifact - Scale factor for the imaginary component. Zero (or blank) defaults - to 1.0. Use a small number for a zero scale factor. + ifact : str + Scale factor for the imaginary component. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. Notes ----- - Allows repeated force load (force, heat flow, etc.) values to be - replaced, added, or ignored. Operations apply to the selected nodes - [NSEL]. and the force labels corresponding to the selected force labels - [DOFSEL]. The operations occur when the next force specifications are - defined. For example, issuing the command F,1,FX,250 after a previous - F,1,FX,200 causes the current value of the force on node 1 in the - x-direction to be 450 with the add operation, 250 with the replace - operation, or 200 with the ignore operation. Scale factors are also - available to multiply the next value before the add or replace - operation. A scale factor of 2.0 with the previous "add" example - results in a force of 700. Scale factors are applied even if no - previous values exist. Issue FCUM,STAT to show the current label, - operation, and scale factors. Solid model boundary conditions are not - affected by this command, but boundary conditions on the FE model are - affected. - - Note:: : FE boundary conditions may still be overwritten by existing - solid model boundary conditions if a subsequent boundary condition - transfer occurs. - - FCUM does not work for tabular boundary conditions. + + .. _FCUM_notes: + + Allows repeated force load (force, heat flow, etc.) values to be replaced, added, or ignored. + Operations apply to the selected nodes [NSEL]. and the force labels corresponding to the selected + force labels ( :ref:`dofsel` ). The operations occur when the next force specifications are defined. + For example, issuing the command :ref:`f`,1,FX,250 after a previous :ref:`f`,1,FX,200 causes the + current value of the force on node 1 in the x-direction to be 450 with the add operation, 250 with + the replace operation, or 200 with the ignore operation. Scale factors are also available to + multiply the next value before the add or replace operation. A scale factor of 2.0 with the previous + "add" example results in a force of 700. Scale factors are applied even if no previous values exist. + Issue :ref:`fcum`,STAT to show the current label, operation, and scale factors. Solid model boundary + conditions are not affected by this command, but boundary conditions on the FE model are affected. + FE boundary conditions may still be overwritten by existing solid model boundary conditions if a + subsequent boundary condition transfer occurs. + + :ref:`fcum` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"FCUM,{oper},{rfact},{ifact}" return self.run(command, **kwargs) - def fdele(self, node="", lab="", nend="", ninc="", lkey="", **kwargs): - """Deletes force loads on nodes. + def fdele( + self, + node: str = "", + lab: str = "", + nend: str = "", + ninc: str = "", + lkey: str = "", + **kwargs, + ): + r"""Deletes force loads on nodes. - APDL Command: FDELE + Mechanical APDL Command: `FDELE `_ Parameters ---------- - node - Node for which force is to be deleted. If ALL, NEND and NINC are - ignored and forces are deleted on all selected nodes [NSEL]. If - NODE = P, graphical picking is enabled and all remaining command - fields are ignored (valid only in the GUI). A component name may - also be substituted for NODE. - - lab - Valid force label. If ALL, use all appropriate labels. Structural - labels: FX, FY, or FZ (forces); MX, MY, or MZ (moments). Thermal - labels: HEAT, HBOT, HE2, HE3, . . ., HTOP (heat flow). Fluid - labels: FLOW (fluid flow). Electric labels: AMPS (current flow), - CHRG (electric charge). Magnetic labels: FLUX (magnetic flux); - CSGX, CSGY, or CSGZ (magnetic current segments). Diffusion labels: - RATE (diffusion flow rate). - - nend, ninc - Delete forces from NODE to NEND (defaults to NODE) in steps of NINC - (defaults to 1). - - lkey + node : str + Node for which force is to be deleted. If ALL, ``NEND`` and ``NINC`` are ignored and forces are + deleted on all selected nodes ( :ref:`nsel` ). If ``NODE`` = P, graphical picking is enabled and + all remaining command fields are ignored (valid only in the GUI). A component name may also be + substituted for ``NODE``. + + lab : str + If ALL, use all appropriate labels. Valid force labels are: + + * **Structural labels** : FX, FY, or FZ (forces); MX, MY, or MZ (moments). + * **Thermal labels** : HEAT, HBOT, HE2, HE3,..., HTOP (heat flow). + * **Fluid label** : FLOW (fluid flow). + * **Electric labels** : AMPS (current flow), CHRG (electric charge). + * **Magnetic labels** : FLUX (magnetic flux); CSGZ (magnetic current segment). + * **Diffusion label** : RATE (diffusion flow rate). + + nend : str + Delete forces from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` (defaults + to 1). + + ninc : str + Delete forces from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` (defaults + to 1). + + lkey : str Lock key: - (blank) - The DOF is not locked (default). + * ``(blank)`` - The DOF is not locked (default). - FIXED - Displacement on the specified degrees of freedom (Lab) is locked. The program - prescribes the degree of freedom to the "current" relative - displacement value in addition to deleting the force. If a - displacement constraint (for example, D command) is applied - in conjunction with this option, the actual applied - displacement will be ramped during the next load step. The - displacement is ramped from the current value to the newly - defined value. This option is only valid for the following - labels: FX, FY, FZ, MX, MY, MZ. This option is intended - primarily for use in the ANSYS Workbench interface to apply - an increment length adjustment (bolt pretension loading). + * ``FIXED`` - Displacement on the specified degrees of freedom ( ``Lab`` ) is locked. The program + prescribes the degree of freedom to the “current” relative displacement value in addition to + deleting the force. If a displacement constraint (for example, :ref:`d` command) is applied in + conjunction with this option, the actual applied displacement will be ramped during the next load + step. The displacement is ramped from the current value to the newly defined value. This option is + only valid for the following labels: FX, FY, FZ, MX, MY, MZ. This option is intended primarily for + use in the Ansys Workbench interface to apply an increment length adjustment (bolt pretension loading). Notes ----- - The node and the degree of freedom label corresponding to the force - must be selected [NSEL, DOFSEL]. + + .. _FDELE_notes: + + The node and the degree of freedom label corresponding to the force must be selected ( :ref:`nsel`, + :ref:`dofsel` ). This command is also valid in PREP7. """ command = f"FDELE,{node},{lab},{nend},{ninc},{lkey}" return self.run(command, **kwargs) - def fj(self, elem="", label="", value="", **kwargs): - """Specify forces or moments on the components of the relative motion of a + def fj(self, elem: str = "", label: str = "", value: str = "", **kwargs): + r"""Specify forces or moments on the components of the relative motion of a joint element. - APDL Command: FJ - joint element. + Mechanical APDL Command: `FJ `_ Parameters ---------- - elem + elem : str Element number or ALL to specify all joint elements. - label + label : str Valid labels: - FX - Force in local x direction. + * ``FX`` - Force in local x direction. - FY - Force in local y direction. + * ``FY`` - Force in local y direction. - FZ - Force in local z direction. + * ``FZ`` - Force in local z direction. - MX - Moment about local x axis. + * ``MX`` - Moment about local x axis. - MY - Moment about local y axis. + * ``MY`` - Moment about local y axis. - MZ - Moment about local z axis. + * ``MZ`` - Moment about local z axis. - value + value : str Value of the label. Notes ----- - Valid for MPC184 (joint options in KEYOPT(1)). - See FJDELE for information on deleting forces and moments. + .. _FJ_notes: + + Valid for ``MPC184`` (joint options in KEYOPT(1)). + + 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. + + See :ref:`fjdele` for information on deleting forces and moments. """ command = f"FJ,{elem},{label},{value}" return self.run(command, **kwargs) - def fjdele(self, elem="", lab="", **kwargs): - """Deletes forces (or moments) on the components of the relative motion of + def fjdele(self, elem: str = "", lab: str = "", **kwargs): + r"""Deletes forces (or moments) on the components of the relative motion of a joint element. - APDL Command: FJDELE - a joint element. + Mechanical APDL Command: `FJDELE `_ Parameters ---------- - elem + elem : str Element number, or ALL. (leaving this blank defaults to ALL) - lab + lab : str Valid labels are: - FX - Force in local x direction. + * ``FX`` - Force in local x direction. - FY - Force in local y direction. + * ``FY`` - Force in local y direction. - FZ - Force in local z direction. + * ``FZ`` - Force in local z direction. - MX - Moment about local x axis. + * ``MX`` - Moment about local x axis. - MY - Moment about local y axis. + * ``MY`` - Moment about local y axis. - MZ - Moment about local z axis. + * ``MZ`` - Moment about local z axis. - ALL, or (blank) - Delete all valid forces or moments. + * ``ALL, or (blank)`` - Delete all valid forces or moments. Notes ----- - Valid for MPC184 (joint options in KEYOPT(1)). - See FJ for information on specifying forces (or moments). + .. _FJDELE_notes: + + Valid for ``MPC184`` (joint options in KEYOPT(1)). + + See :ref:`fj` for information on specifying forces (or moments). """ command = f"FJDELE,{elem},{lab}" return self.run(command, **kwargs) - def fjlist(self, elem="", **kwargs): - """Lists forces and moments applied on joint elements. + def fjlist(self, elem: str = "", **kwargs): + r"""Lists forces and moments applied on joint elements. - APDL Command: FJLIST + Mechanical APDL Command: `FJLIST `_ Parameters ---------- - elem - Element number or ALL (or blank). Lists joint element forces and - moments on the specified element(s). + elem : str + Element number or ALL (or blank). Lists joint element forces and moments on the specified + element(s). Notes ----- - Valid for MPC184 joint elements. See FJ for information on specifying - forces and moments. + + .. _FJLIST_notes: + + Notes + Valid for ``MPC184`` joint elements. See :ref:`fj` for information on specifying forces and moments. """ command = f"FJLIST,{elem}" return self.run(command, **kwargs) - def flist(self, node1="", node2="", ninc="", **kwargs): - """Lists force loads on the nodes. + def flist(self, node1: str = "", node2: str = "", ninc: str = "", **kwargs): + r"""Lists force loads on the nodes. - APDL Command: FLIST + Mechanical APDL Command: `FLIST `_ Parameters ---------- - node1, node2, ninc - List forces for nodes NODE1 to NODE2 (defaults to NODE1) in steps - of NINC (defaults to 1). If ALL, list for all selected nodes - [NSEL] and NODE2 and NINC are ignored (default). If NODE1 = 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 NODE1. + node1 : str + List forces for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL, list for all selected nodes ( :ref:`nsel` ) and ``NODE2`` and ``NINC`` + are ignored (default). If ``NODE1`` = 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 + ``NODE1``. + + node2 : str + List forces for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL, list for all selected nodes ( :ref:`nsel` ) and ``NODE2`` and ``NINC`` + are ignored (default). If ``NODE1`` = 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 + ``NODE1``. + + ninc : str + List forces for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of ``NINC`` + (defaults to 1). If ALL, list for all selected nodes ( :ref:`nsel` ) and ``NODE2`` and ``NINC`` + are ignored (default). If ``NODE1`` = 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 + ``NODE1``. Notes ----- - Listing applies to the selected nodes [NSEL] and the selected force - labels [DOFSEL]. - Caution:: : A list containing a node number that is larger than the - maximum defined node (NODE2), could deplete the system memory and - produce unpredictable results. + .. _FLIST_notes: + + Listing applies to the selected nodes ( :ref:`nsel` ) and the selected force labels ( :ref:`dofsel` + ). + + .. warning:: + + A list containing a node number that is larger than the maximum defined node ( NODE2), could + deplete the system memory and produce unpredictable results. This command is valid in any processor. """ command = f"FLIST,{node1},{node2},{ninc}" return self.run(command, **kwargs) - def fssect(self, rho="", nev="", nlod="", kbr="", **kwargs): - """Calculates and stores total linearized stress components. + def fscale(self, rfact: str = "", ifact: str = "", **kwargs): + r"""Scales force load values in the database. - APDL Command: FSSECT + Mechanical APDL Command: `FSCALE `_ Parameters ---------- - rho - In-plane (X-Y) average radius of curvature of the inside and - outside surfaces of an axisymmetric section. If zero (or blank), a - plane or 3-D structure is assumed. If nonzero, an axisymmetric - structure is assumed. Use a suitably large number (see the - Mechanical APDL Theory Reference) or use -1 for an axisymmetric - straight section. - - nev - Event number to be associated with these stresses (defaults to 1). - - nlod - Loading number to be associated with these stresses (defaults to - 1). + rfact : str + Scale factor for the real component. Zero (or blank) defaults to 1.0. Use a small number for a + zero scale factor. - kbr - For an axisymmetric analysis (RHO ≠ 0): - - 0 - Include the thickness-direction bending stresses - - 1 - Ignore the thickness-direction bending stresses - - 2 - Include the thickness-direction bending stress using the same formula as the Y - (axial direction ) bending stress. Also use the same formula - for the shear stress. + ifact : str + Scale factor for the imaginary component. Zero (or blank) defaults to 1.0. Use a small number + for a zero scale factor. Notes ----- - Calculates and stores the total linearized stress components at the - ends of a section path [PATH] (as defined by the first two nodes with - the PPATH command). The path must be entirely within the selected - elements (that is, there must not be any element gaps along the path). - Stresses are stored according to the fatigue event number and loading - number specified. Locations (one for each node) are associated with - those previously defined for these nodes [FL] or else they are - automatically defined. Stresses are separated into six total - components (SX through SXZ) and six membrane-plus-bending (SX through - SXZ) components. The temperature at each end point and the current - time are also stored along with the total stress components. - Calculations are made from the stresses currently in the database (last - SET or LCASE command). Stresses are stored as section coordinate - components if axisymmetric or as global Cartesian coordinate components - otherwise, regardless of the active results coordinate system [RSYS]. - The FSLIST command may be used to list stresses. The FS command can be - used to modify stored stresses. See also the PRSECT and PLSECT - commands for similar calculations. - """ - command = f"FSSECT,{rho},{nev},{nlod},{kbr}" - return self.run(command, **kwargs) - - def fscale(self, rfact="", ifact="", **kwargs): - """Scales force load values in the database. - - APDL Command: FSCALE - - Parameters - ---------- - rfact - Scale factor for the real component. Zero (or blank) defaults to - 1.0. Use a small number for a zero scale factor. - ifact - Scale factor for the imaginary component. Zero (or blank) defaults - to 1.0. Use a small number for a zero scale factor. + .. _FSCALE_notes: - Notes - ----- - Scales force load (force, heat flow, etc.) values in the database. - Scaling applies to the previously defined values for the selected nodes - [NSEL] and the selected force labels [DOFSEL]. Issue FLIST command to - review results. Solid model boundary conditions are not scaled by this - command, but boundary conditions on the FE model are scaled. - - Note:: : Such scaled FE boundary conditions may still be overwritten by - unscaled solid model boundary conditions if a subsequent boundary + Scales force load (force, heat flow, etc.) values in the database. Scaling applies to the previously + defined values for the selected nodes ( :ref:`nsel` ) and the selected force labels ( :ref:`dofsel` + ). Issue :ref:`flist` command to review results. Solid model boundary conditions are not scaled by + this command, but boundary conditions on the FE model are scaled. Such scaled FE boundary conditions + may still be overwritten by unscaled solid model boundary conditions if a subsequent boundary condition transfer occurs. - FSCALE does not work for tabular boundary conditions. + :ref:`fscale` does not work for tabular boundary conditions. This command is also valid in PREP7. """ diff --git a/src/ansys/mapdl/core/_commands/solution/fe_surface_loads.py b/src/ansys/mapdl/core/_commands/solution/fe_surface_loads.py index 97be8b4776a..acb03addb07 100644 --- a/src/ansys/mapdl/core/_commands/solution/fe_surface_loads.py +++ b/src/ansys/mapdl/core/_commands/solution/fe_surface_loads.py @@ -22,233 +22,751 @@ class FeSurfaceLoads: - def sf(self, nlist="", lab="", value="", value2="", **kwargs): - """Specifies surface loads on nodes. - APDL Command: SF + def sf( + self, + nlist: str = "", + lab: str = "", + value: str = "", + value2: str = "", + meshflag: str = "", + **kwargs, + ): + r"""Defines surface loads on nodes. + + Mechanical APDL Command: `SF `_ Parameters ---------- - nlist - Nodes defining the surface upon which the load is to be applied. - Use the label ALL or P, or a component name. If ALL, all selected - nodes [NSEL] are used (default). If P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). - - lab - Valid surface load label. Load labels are listed under "Surface - Loads" in the input table for each element type in the Element - Reference. - - value - Surface load value or table name reference for specifying tabular - boundary conditions. - - value2 + nlist : str + Nodes defining the surface upon which the load is to be applied. Use the label ALL or P, or a + component name. If ALL, all selected nodes ( :ref:`nsel` ) are used (default). If P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). + + lab : str + Valid surface load label. Load labels are listed under **Surface Loads** in the input table for each element type. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above... _sf1: + + Thermal labels CONV and HFLUX are mutually exclusive. + + .. _sf2: + + For an acoustic analysis, apply the fluid-structure interaction flag (Label = FSI) to only the + ``FLUID29``, ``FLUID30``, ``FLUID220``, and ``FLUID221`` elements. + + value : str + Surface load value or table name reference for specifying tabular boundary conditions. + + If ``Lab`` = PRES, ``VALUE`` is the real component of the pressure. + + If ``Lab`` = CONV: + + * ``VALUE`` is typically the film coefficient and ``VALUE2`` (below) is typically the bulk + temperature. If ``VALUE`` = - ``N``, the film coefficient may be a function of temperature and is + determined from the HF property table for material ``N`` ( :ref:`mp` ). (See the :ref:`scopt` + command for a way to override this option and use - ``N`` as the film coefficient.) The + temperature used to evaluate the film coefficient is usually the average between the bulk and wall + temperatures, but may be user-defined for some elements. + * If :ref:`kbc`,0 has been issued for ramped loads, it affects only ``VALUE2`` :ref:`the bulk + temperature, and the film coefficient specification is unaffected. ` + * In a viscous-thermal acoustic analysis, if ``Lab`` = CONV, ``VALUE`` is the real part of the heat + flux and ``VALUE2`` is the imaginary part of the heat flux. + + If ``Lab`` = RAD, ``VALUE`` is surface emissivity. + + If ``Lab`` = PORT, ``VALUE`` is a port number representing a waveguide exterior port. The port + number must be an integer between 1 and 50. For acoustic 2×2 transfer admittance matrix, the port + number can be any positive integer. The smaller port number corresponds to the port 1 of the 2×2 + transfer admittance matrix and the greater number corresponds to the port 2. If one port of the + transfer admittance matrix is connecting to the acoustic-structural interaction interface, the port + number corresponds to the port 2 of the transfer admittance matrix. A pair of ports of the 2×2 + transfer admittance matrix must be defined in the same element. In an acoustic analysis, the + positive port number defines a transparent port, through which the reflected sound pressure wave + propagates to the infinity; the negative port number defines a vibro port that is the structural + vibration surface. + + If ``Lab`` = SHLD, ``VALUE`` is the surface normal velocity in a harmonic analysis or in a transient + analysis solved with the velocity potential formulation; ``VALUE`` is the surface normal + acceleration in a transient analysis solved with the pressure formulation. + + If ``Lab`` = IMPD, ``VALUE`` is resistance in (N)(s)/m :sup:`3` if ``VALUE`` > 0 and is conductance + in mho if ``VALUE`` < 0 for acoustic or harmonic response analyses. In acoustic transient analyses, + ``VALUE2`` is not used. + + If ``Lab`` = RDSF, ``VALUE`` is the emissivity value; the following conditions apply: If ``VALUE`` + is between 0 and 1, apply a single value to the surface. If ``VALUE`` = - ``N``, the emissivity may + be a function of the temperature, and is determined from the EMISS property table for material ``N`` + ( :ref:`mp` ). The material ``N`` does not need to correlate with the underlying solid thermal + elements. + + If ``Lab`` = FSIN in a one-way structure-to-acoustic coupling, ``VALUE`` is the surface interface + number. + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL to CFX analysis, ``VALUE`` is not used. + + If ``Lab`` = ATTN, ``VALUE`` is the absorption coefficient of the surface. + + If ``Lab`` = VIMP, ``VALUE`` is resistance of viscous impedance in (N)(s)/m :sup:`3`. + + If ``Lab`` = TIMP, ``VALUE`` is resistance of thermal impedance in (N)(s)/m :sup:`3`. + + If ``Lab`` = PERM, ``VALUE`` is permeability in m :sup:`2`. + + value2 : str Second surface load value (if any). + If ``Lab`` = PRES, this value is the imaginary pressure component, used by the following supported elements: + + * Surface elements: ``SURF153``, ``SURF154`` and ``SURF159``. + + * Solid and solid-shell elements: ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, + ``SOLID187``, ``SOLSH190``, and ``SOLID285``. + + * Shell elements: ``SHELL181``, ``SHELL281``, ``SHELL208``, and ``SHELL209``. + + * Coupled-field elements with structural degrees of freedom: ``PLANE222``, ``PLANE223``, + ``SOLID225``, ``SOLID226``, and ``SOLID227``. + + Supported analysis types in this case are: + + * Full harmonic ( :ref:`hropt`,FULL) + + * Mode-superposition harmonic ( :ref:`hropt`,MSUP), if the mode-extraction method is Block Lanczos ( + :ref:`modopt` ,LANB), PCG Lanczos ( :ref:`modopt`,LANPCG), Supernode ( :ref:`modopt`,SNODE), + Subspace ( :ref:`modopt`,SUBSP), or Unsymmetric ( :ref:`modopt`,UNSYM) + + If ``Lab`` = CONV: + + * ``VALUE2`` is the bulk temperature for thermal analyses. + * If :ref:`kbc`,0 has been issued for ramped loads, the bulk temperature is ramped from the value + defined by :ref:`tunif` to the value specified by ``VALUE2`` for the first loadstep. If + :ref:`tabular boundary conditions are defined, the ` :ref:`kbc` command is ignored and + tabular values are used. + * For viscous-thermal acoustics ``VALUE2`` is the imaginary part of heat flux. + + If ``Lab`` = RAD, ``VALUE2`` is the ambient temperature. + + If ``Lab`` = SHLD, ``VALUE2`` is the phase angle of the normal surface velocity (defaults to zero) + for harmonic response analyses while ``VALUE2`` is not used for transient analyses in acoustics. + + If ``Lab`` = IMPD, ``VALUE2`` is reactance in (N)(s)/m :sup:`3` if ``VALUE`` > 0 and is the product + of susceptance and angular frequency if ``VALUE`` < 0 for acoustics. + + If ``Lab`` = RDSF, ``VALUE2`` is the enclosure number. Radiation will occur between surfaces flagged + with the same enclosure numbers. If the enclosure is open, radiation will also occur to ambient. If + ``VALUE2`` is negative radiation direction is reversed and will occur inside the element for the + flagged radiation surfaces. + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL to CFX analysis, ``VALUE2`` is the surface interface + number (not available from within the GUI). + + If ``Lab`` = PORT, ``VALUE2`` is not used. + + If ``Lab`` = ATTN, ``VALUE2`` is the transmission loss (dB) of the coupled wall in an energy + diffusion solution for room acoustics. + + If ``Lab`` = VIMP, ``VALUE2`` is reactance of viscous impedance in (N)(s)/m :sup:`3`. + + If ``Lab`` = TIMP, ``VALUE2`` is reactance of thermal impedance in (N)(s)/m :sup:`3`. + + meshflag : str + Specifies how to apply normal pressure loading on the mesh. Valid in a `nonlinear adaptivity + analysis `_ + when ``Lab`` = PRES and ``Nlist`` is a nodal component defined prior to any remeshing activity. + + 0 - Pressure loading occurs on the current mesh (default). + + 1 - Pressure loading occurs on the initial mesh for nonlinear adaptivity. + Notes ----- - Individual nodes may not be entered for this command. The node list is - to identify a surface and the Nlist field must contain a sufficient - number of nodes to define an element surface. The loads are internally - stored on element faces defined by the specified nodes. All nodes on - an element face (including midside nodes, if any) must be specified for - the face to be used, and the element must be selected. - - If all nodes defining a face are shared by an adjacent face of another - selected element, the face is not free and will not have a load - applied. If more than one element can share the same nodes (for - example, a surface element attached to a solid element), select the - desired element type before issuing the SF command. The SF command - applies only to area and volume elements. - - For shell elements, if the specified nodes include face one (which is - usually the bottom face) along with other faces (such as edges), only - face one is used. Where faces cannot be uniquely determined from the - nodes, or where the face does not fully describe the load application, - use the SFE command. A load key of 1 (which is typically the first - loading condition on the first face) is used if the face determination - is not unique. A uniform load value is applied over the element face. + + .. _SF_notes: + + Individual nodes cannot be entered for this command. The node list is to identify a surface and the + ``Nlist`` field must contain a sufficient number of nodes to define an element surface. The loads + are internally stored on element faces defined by the specified nodes. All nodes on an element face + (including midside nodes, if any) must be specified for the face to be used, and the element must be + selected. + + If all nodes defining a face are shared by an adjacent face of another selected element, the face is + not free and will not have a load applied. If more than one element can share the same nodes (for + example, a surface element attached to a solid element), select the desired element type before + issuing the :ref:`sf` command. The :ref:`sf` command applies only to area and volume elements. + + For shell elements, if the specified nodes include face one (which is usually the bottom face) along + with other faces (such as edges), only face one is used. Where faces cannot be uniquely determined + from the nodes, or where the face does not fully describe the load application, issue :ref:`sfe` + instead of :ref:`sf`. A load key of 1 (which is typically the first loading condition on the first + face) is used if the face determination is not unique. A uniform load value is applied over the + element face. + + You can use these related surface-load commands with :ref:`sf` : + + * :ref:`sfe` - Defines surface loads on elements. You can also use it to apply tapered loads on + individual element faces. + * :ref:`sfbeam` - Applies surface loads to beam elements. + * :ref:`sfcontrol` - Applies general (normal, tangential, and other) surface loads to `supported + structural elements + `_. + * :ref:`sfcum` - Accumulates (adds) surface loads applied via :ref:`sf`. + * :ref:`sfdele` - Delete loads applied via :ref:`sf`. + * :ref:`sffun` - Applies loads from a node-vs.-value function. + * :ref:`sfgrad` - Applies an alternate tapered load. + + Tabular boundary conditions Tabular boundary conditions ( ``VALUE`` = ``tabname`` and/or ``VALUE2`` + = ``tabname``) are available + for the following surface load labels ( ``Lab`` ) only: PRES (real and/or imaginary components), + CONV (film coefficient and/or bulk temperature; or heat flux for viscous-thermal acoustics), HFLUX, + DFLUX (diffusion flux), RAD (surface emissivity and ambient temperature), IMPD (resistance and + reactance), SHLD (normal velocity and phase or acceleration), ATTN ( absorption coefficient or + transmission loss ), VIMP (viscous impedance), and TIMP (thermal impedance). Issue :ref:`dim` to + define a table. + + 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. + + This command is also valid in the PREP7 and :ref:`slashmap` processors. + + .. _SF_prodres: + + Ansys Mechanical Enterprise :ref:`sf`,FSI and :ref:`sf`,FSIN are available only in the Ansys + Mechanical Enterprise family of products (Ansys Mechanical Enterprise, + Ansys Mechanical Enterprise PrepPost, and Ansys Mechanical Enterprise Solver). """ - command = f"SF,{nlist},{lab},{value},{value2}" + command = f"SF,{nlist},{lab},{value},{value2},,{meshflag}" return self.run(command, **kwargs) def sfbeam( self, - elem="", - lkey="", - lab="", - vali="", - valj="", - val2i="", - val2j="", - ioffst="", - joffst="", - lenrat="", + elem: str = "", + lkey: str = "", + lab: str = "", + vali: str = "", + valj: str = "", + val2i: str = "", + val2j: str = "", + ioffst: str = "", + joffst: str = "", + lenrat: int | str = "", **kwargs, ): - """Specifies surface loads on beam and pipe elements. + r"""Specifies surface loads on beam and pipe elements. - APDL Command: SFBEAM + Mechanical APDL Command: `SFBEAM `_ Parameters ---------- - elem - Element to which surface load is applied. If ALL, apply load to - all selected beam elements (ESEL). If Elem = P, graphical picking - is enabled and all remaining command fields are ignored (valid only - in the GUI). A component name may be substituted in Elem. - - lkey - Load key associated with surface load (defaults to 1). Load keys - (1, 2, 3, etc.) are listed under "Surface Loads" in the input table - for each element type in the Element Reference. For beam and some - pipe elements, the load key defines the load orientation. - - lab - Valid surface load label. Load labels are listed under "Surface - Loads" in the input table for each element type in the Element - Reference. Structural labels: PRES (pressure). - - vali, valj - Surface load values at nodes I and J. If VALJ is blank, it - defaults to VALI. If VALJ is zero, a zero is used. - - val2i, val2j - Second surface load values at nodes I and J. Currently not used. - - ioffst, joffst - Offset distance from node I (toward node J) where VALI is applied, - and offset distance from node J (toward node I) where VALJ is - applied, respectively. - - lenrat + elem : str + Element to which surface load is applied. If ALL, apply load to all selected beam 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 be substituted in ``Elem``. + + lkey : str + Load key associated with surface load (defaults to 1). Load keys (1, 2, 3, etc.) are listed + under "Surface Loads" in the input table for each element type in the `Element Reference + `_. For beam + and some pipe elements, the load key defines the load orientation. + + lab : str + Valid surface load label. Load labels are listed under "Surface Loads" in the input table for + each element type in the `Element Reference + `_. + Structural labels: PRES (pressure). + + vali : str + Surface load values at nodes I and J. If ``VALJ`` is blank, it defaults to ``VALI``. If ``VALJ`` + is zero, a zero is used. + + valj : str + Surface load values at nodes I and J. If ``VALJ`` is blank, it defaults to ``VALI``. If ``VALJ`` + is zero, a zero is used. + + val2i : str + Second surface load values at nodes I and J. Currently not used. + + val2j : str + Second surface load values at nodes I and J. Currently not used. + + ioffst : str + Offset distance from node I (toward node J) where ``VALI`` is applied, and offset distance from + node J (toward node I) where ``VALJ`` is applied, respectively. + + joffst : str + Offset distance from node I (toward node J) where ``VALI`` is applied, and offset distance from + node J (toward node I) where ``VALJ`` is applied, respectively. + + lenrat : int or str Offset distance flag: - 0 - Offset is in terms of length units (default). + * ``0`` - Offset is in terms of length units (default). - 1 - Offset is in terms of a length ratio (0.0 to 1.0). + * ``1`` - Offset is in terms of a length ratio (0.0 to 1.0). Notes ----- - Specifies surface loads on the selected beam elements. Distributed - loads are applied on a force-per-length basis (that is, the width of - the underlying element is not considered). To list and delete surface - loads applied with this command, use the SFELIST and SFEDELE commands, + + .. _SFBEAM_notes: + + Specifies surface loads on the selected beam elements. Distributed loads are applied on a force-per- + length basis (that is, the width of the underlying element is not considered). To list and delete + surface loads applied with this command, use the :ref:`sfelist` and :ref:`sfedele` commands, respectively. - If no offset values (IOFFSET and JOFFSET) are specified, the load is - applied over the full element length. Values may also be input as - length fractions, depending on the LENRAT setting. For example, - assuming a line length of 5.0, an IOFFST of 2.0 with LENRAT = 0 or an - IOFFST of 0.4 with LENRAT = 1 represent the same point. If JOFFST = - -1, VALI is assumed to be a point load at the location specified via - IOFFST, and VALJ is ignored. (IOFFSET cannot be equal to -1.) The - offset values are stepped even if you issue a KBC,0 command. - - Offsets are only available for element types BEAM188 and PIPE288 if - using the cubic shape function (KEYOPT(3) = 3) for those element types. - - To accumulate (add) surface loads applied with this command, use the - SFCUM,,ADD command. Use the same offset values used on the previous - SFBEAM command (for a given element face); otherwise, the loads do not - accumulate. If no offsets are specified, the command applies the + If no offset values ( ``IOFFSET`` and ``JOFFSET`` ) are specified, the load is applied over the full + element length. Values may also be input as length fractions, depending on the ``LENRAT`` setting. + For example, assuming a line length of 5.0, an ``IOFFST`` of 2.0 with ``LENRAT`` = 0 or an + ``IOFFST`` of 0.4 with ``LENRAT`` = 1 represent the same point. If ``JOFFST`` = -1, ``VALI`` is + assumed to be a point load at the location specified via ``IOFFST``, and ``VALJ`` is ignored. ( + ``IOFFSET`` cannot be equal to -1.) The offset values are stepped even if you issue a :ref:`kbc`,0 + command. + + Offsets are only available for element types ``BEAM188`` and ``PIPE288`` if using the cubic shape + function (KEYOPT(3) = 3) for those element types. + + To accumulate (add) surface loads applied with this command, use the :ref:`sfcum`,,ADD command. Use + the same offset values used on the previous :ref:`sfbeam` command (for a given element face); + otherwise, the loads do not accumulate. If no offsets are specified, the command applies the previous offset values. + 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. + This command is also valid in PREP7. """ command = f"SFBEAM,{elem},{lkey},{lab},{vali},{valj},{val2i},{val2j},{ioffst},{joffst},{lenrat}" return self.run(command, **kwargs) - def sfcum(self, lab="", oper="", fact="", fact2="", **kwargs): - """Specifies that surface loads are to be accumulated. + def sfcontrol( + self, + kcsys: str = "", + lcomp: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + ktaper: str = "", + kuse: str = "", + karea: str = "", + kproj: str = "", + kfollow: str = "", + **kwargs, + ): + r"""Defines structural surface-load properties on selected elements and nodes for subsequent loading + commands. + + Mechanical APDL Command: `SFCONTROL `_ + + Parameters + ---------- + kcsys : str + Specifies how the load direction is determined: + + * 0 (or blank) - Use the coordinate system of an element face. A local coordinate system is + projected onto the face, if defined ( ``VAL1`` ) (default). + * 1 - Use a local coordinate system. A local coordinate system must be defined and is not projected + onto the face. + * 2 - Use a custom (user-defined) vector in the global Cartesian coordinate system. + + lcomp : str + Load-component definition when ``KCSYS`` = 0 or 1. The following table shows how the component + (or primary direction) is determined :ref:`based on the coordinate system: ` + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + val1 : str + **When** ``KCSYS`` = 0: + + * ``VAL1`` - Determines the first tangential axis (x axis). Not valid for the edges of 3D shell or + 2D elements. + * 0 - Aligns the x axis to the first parametric direction :math:`equation not available` (default). + * 1 - Aligns x axis to the second parametric direction :math:`equation not available`. + * >10 - ID of the local coordinate system. The local coordinate system is projected to selected face + of the element. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Rotation angle of a tangential load (optional). Not valid for the edges of 3D shell or + 2D elements. If this value is specified, the tangential load rotates further with respect to the + surface normal. The load component ( ``LCOMP`` ) becomes the reference axis to rotate. + + **When** ``KCSYS`` = 1: + + * ``VAL1`` - ID of the local coordinate system for the load. The axes of the local coordinate system + are fixed in the global cartesian coordinate system. + * ``VAL2`` - Not used. + * ``VAL3`` - Not used. + **When** ``KCSYS`` = 2: + + * ``VAL1``, ``VAL2``, ``VAL3`` - The X / Y / Z components, respectively, of the direction vector in + the global Cartesian coordinate system. + + val2 : str + **When** ``KCSYS`` = 0: + + * ``VAL1`` - Determines the first tangential axis (x axis). Not valid for the edges of 3D shell or + 2D elements. + * 0 - Aligns the x axis to the first parametric direction :math:`equation not available` (default). + * 1 - Aligns x axis to the second parametric direction :math:`equation not available`. + * >10 - ID of the local coordinate system. The local coordinate system is projected to selected face + of the element. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Rotation angle of a tangential load (optional). Not valid for the edges of 3D shell or + 2D elements. If this value is specified, the tangential load rotates further with respect to the + surface normal. The load component ( ``LCOMP`` ) becomes the reference axis to rotate. + + **When** ``KCSYS`` = 1: + + * ``VAL1`` - ID of the local coordinate system for the load. The axes of the local coordinate system + are fixed in the global cartesian coordinate system. + * ``VAL2`` - Not used. + * ``VAL3`` - Not used. + **When** ``KCSYS`` = 2: + + * ``VAL1``, ``VAL2``, ``VAL3`` - The X / Y / Z components, respectively, of the direction vector in + the global Cartesian coordinate system. + + val3 : str + **When** ``KCSYS`` = 0: + + * ``VAL1`` - Determines the first tangential axis (x axis). Not valid for the edges of 3D shell or + 2D elements. + * 0 - Aligns the x axis to the first parametric direction :math:`equation not available` (default). + * 1 - Aligns x axis to the second parametric direction :math:`equation not available`. + * >10 - ID of the local coordinate system. The local coordinate system is projected to selected face + of the element. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Rotation angle of a tangential load (optional). Not valid for the edges of 3D shell or + 2D elements. If this value is specified, the tangential load rotates further with respect to the + surface normal. The load component ( ``LCOMP`` ) becomes the reference axis to rotate. + + **When** ``KCSYS`` = 1: + + * ``VAL1`` - ID of the local coordinate system for the load. The axes of the local coordinate system + are fixed in the global cartesian coordinate system. + * ``VAL2`` - Not used. + * ``VAL3`` - Not used. + **When** ``KCSYS`` = 2: + + * ``VAL1``, ``VAL2``, ``VAL3`` - The X / Y / Z components, respectively, of the direction vector in + the global Cartesian coordinate system. + + ktaper : str + Global tapered load behavior (valid for :ref:`sfe` only): + + * 0 - Load does not vary (default). + * 1 - Load varies with respect to the current element locations. The magnitude changes with respect + to the element deformation. + * 2 - Load varies with respect to the initial element locations. The load magnitude for each element + remains constant throughout the solution.. + + For more information, see :ref:`globaltaperedloads`. + + kuse : str + Load direction with respect to the surface normal of the selected face: + + * 0 - Use the load as calculated (default). + * 1 - Use a positive load only (negative set to zero, valid for ``LCOMP`` = 0 and ``KCSYS`` = 0). + * 2 - Use a negative load only (positive set to zero, valid for ``LCOMP`` = 0 and ``KCSYS`` = 0). + * 3 - Applied load is not used if the surface normal is oriented in the same general direction as + the user-defined vector. Valid for ``KCSYS`` = 2 only. + + karea : str + Loaded area during large deformation: + + * 0 - Use the current (deformed) area (default). + * 1 - Use the initial area. + + kproj : str + Vector-oriented load ( ``KCSYS`` = 2) behavior: + + * 0 - Apply the load on the full area and include the tangential component (default). + * 1 - Apply the load on the projected area and include the tangential component. + * 2 - Apply the load on the projected area and exclude the tangential component. + + kfollow : str + Controls follower-load behavior. Valid when ``KCSYS`` = 1 or 2, or when ``KCSYS`` = 0 and ``VAL1`` > + 10. + + * 0 - The load maintains a fixed direction (default). + * 1 -The load follows the element deformation. + + For more information, see :ref:`scfofollowloadbehav`. + + Notes + ----- + + .. _SFCONTROL_notes: + + :ref:`sfcontrol` defines the properties of structural distributed loads for all subsequent :ref:`sf` + or :ref:`sfe` loading commands. ( :ref:`sfa` and :ref:`sfl` are not supported.) + + The command does not support analyses in which remeshing occurs, such as nonlinear mesh adaptivity + and 2D to 3D analysis. + + To update a load property or properties, reissue :ref:`sfcontrol` with the new option(s) before + issuing further :ref:`sf` or :ref:`sfe` commands. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + To list the current set of control data, issue :ref:`sfcontrol`,STAT. + + To reset all input values to defaults, issue :ref:`sfcontrol`,NONE. + + When ``KCSYS`` = 0, the positive normal load acts in the negative surface normal (- ``z`` ) + direction. The positive tangential loads act in the positive coordinate direction. A user-defined + coordinate system ( ``VAL1`` ) is ignored if the load is applied on an edge of a plane element ( + ``PLANE182``, ``PLANE183``, ``SHELL208``, ``SHELL209``, ``PLANE222``, and ``PLANE223`` ). + + When ``KCSYS`` = 1, the loading direction follows the positive direction of the local coordinate + system. The ID of a local coordinate system ( ``VAL1`` ) is required. + + The following figure shows how the coordinate directions are determined on a face of a solid or + shell element with different ``KCSYS`` and ``VAL1`` input: + + Coordinate System for Load Application on the Faces of 3D Solid and Shell Elements + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + * where: + * z, x :sub:`1`, y :sub:`1` : normal and tangential directions (default surface coordinate system) + * z, x :sub:`2`, y :sub:`2` : normal and user-defined tangential directions (user-defined surface + coordinate system) + * x :sub:`3`, y :sub:`3`, z :sub:`3` : x, y, and z directions defined by the local coordinate system + when ``KCSYS`` = 1 + + **When** ``KCSYS`` = 0: + + * The parametric direction determines the default coordinate system on a face. By default, the first + parametric direction ( :math:`equation not available` ) becomes the first tangential direction (x + direction). If ``VAL1`` = 1, the second parametric direction ( :math:`equation not + available` ) is selected as the x direction. + * For the projected local coordinate system ( ``VAL1`` > 10), the direction of the first tangential + axes (x :sub:`2` ) is determined by the projection of the local coordinate system onto the face. + The projected tangential axes may rotate if the direction of the face normal (z) changes in the + space during solution. If the direction of the face normal (z) is fixed (for in-plane rotation, + for example), the tangential axes do not follow element deformation. To enable your coordinate + system to always follow the element deformation, specify the follower option ( ``KFOLLOW`` ). + * **Coordinate System vs. Load Direction** + * For the loads defined in the default coordinate system ( ``KCSYS`` = 0), the tangential direction + of a load is restricted because it is aligned to the direction of the axis ( ``LCOMP`` ). The load + direction can be arbitrary by adding additional rotation to the load ( ``VAL3`` ). The following + figure shows how the load direction is determined on the face of an element. If ``VAL3`` > 0, + ``LCOMP`` becomes the reference axis to define the rotation. + + Load Direction in the Default Coordinate System + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + **When** ``KCSYS`` = 1: + + * The positive direction of the x :sub:`3`, y :sub:`3`, and z :sub:`3` axes follow the direction of + the local coordinate system without adjustment. Therefore, they do not follow element deformation. + + **When** ``KCSYS`` = 2: + + * The loading direction follows the positive direction of the orientation vector, defined via + ``VAL1``, ``VAL2``, and ``VAL3``. The direction is calculated as :math:`equation not available`, + where :math:`equation not available`, :math:`equation not available`, and :math:`equation not + available` are unit vectors in the global Cartesian coordinate system. The loading + direction is fixed and does not follow the deformation of a face of a selected element. + * You can adjust the load magnitude ( ``KUSE`` and ``KPROJ`` ). + * Use the follower option ( ``KFOLLOW`` ) to specify whether the load has a fixed direction ( + ``KCSYS`` = 1 or 2), or projects the local coordinate system to the element face to follow element + deformation ( ``KCSYS`` = 0 and ``VAL1`` > 10). + + The following figure shows the default direction of the normal (z) and tangential (x) components on + an edge of a 3D shell element ( ``SHELL181`` or ``SHELL281`` ). + + Default Coordinate System of Surface Load on the Edge of a 3D Shell Element + If a local coordinate system is defined and ``KCSYS`` = 0 for the edge of the 3D shell element, the + tangential directions are adjusted in the plane of the edge. + + Projected Coordinate System of Surface Load on the Edge of a 3D Shell Element + The following figure shows the positive direction of the loads on the edge of a plane element when + ``KCSYS`` = 0. The positive direction of the tangential load is defined by the definition of the + faces (J-I, K-J, L-K, I-L). + + Positive Tangential Load on the Edge of a Plane Element + If ``KCSYS`` = 1 or 2, the load direction does not change and ``KUSE`` = 1 or 2 is ignored. + + If ``KCSYS`` = 1 or 2, or ``KTAPER`` > 0, you cannot specify a gradient (slope) for surface loads ( + :ref:`sfgrad` ) or a varying surface load ( :ref:`sffun` ). + + This command is also valid in the PREP7 processor. + + .. _globaltaperedloads: + + If ``KTAPER`` = 1, the magnitude of the load is determined by the current location of a point: + + .. math:: + + equation not available + + * where: + * :math:`equation not available` : Values on :ref:`sfe` ( ``VAL1`` ~ ``VAL4`` ) + * :math:`equation not available` : Global Cartesian coordinates at the current location of the + point. + + If ``KTAPER`` = 2, the magnitude of the load is determined by the initial location of a point: + + .. math:: + + equation not available + + * where: + * :math:`equation not available` : Values on :ref:`sfe` ( ``VAL1`` ~ ``VAL4`` ) + * :math:`equation not available` : Global Cartesian coordinates at the initial location of the + point. + + ``KTAPER`` is not valid for use with :ref:`sf`. + + .. _scfofollowloadbehav: + + The follower option ( ``KFOLLOW`` ) determines whether the load maintains a fixed direction + (default) or follows element deformation. The option applies to surface loads defined by a fixed + direction ( ``KCSYS`` = 1 or 2) or by a projected user-defined coordinate system ( ``KCSYS`` = 0 and + ``VAL1`` > 10). + + **When** ``KCSYS`` = 0 and ``VAL1`` > 10: + + The selected local coordinate system is projected onto the face at the initial state, then the + projected tangential component ( ``LCOMP`` ) is attached to the orthonormal basis ( **e** :sub:`1`, + **e** :sub:`2`, **e** :sub:`3` ) of the face. The orthonormal basis may or may not be coincident to + the :math:`equation not available` coordinate system. During solution, the basis is updated at the + current time step and the load direction is updated with respect to the basis. + + Follower Load Behavior in the Projected Coordinate System + **When** ``KCSYS`` = 1 or 2: + + The global direction vector is attached to the orthonormal basis of selected face at the initial + state. When ``KCSYS`` = 1, the direction of selected axis is considered as the direction vector and + attached to the basis. During solution, the basis is updated at current time step and the load + direction is updated with respect to the basis. + + Follower Load Behavior for a User-Defined Orientation + **Follower loads on the edges of 3D shell and 2D elements:** + + The load is attached to the basis defined on the edge ( **e** :sub:`t`, **e** :sub:`ne`, **e** + :sub:`nf` [tangential, edge-normal, and face-normal vector, respectively]). For 2D solid elements, + the face-normal orientation ( **e** :sub:`nf` ) is that of the global Z axis. For 2D shell elements, + the edge-normal ( **e** :sub:`ne` ) is that of the global Z axis. + + Follower Load Behavior on the Edges of 3D Shell and 2D Elements + If it is necessary to use the follower option after the first load step or at the restart analysis, + define the load direction with respect to the current geometry (that is, the current basis of an + element face). The follower option for the local coordinate system ( ``KCSYS`` = 1) is not allowed + after the first load step or at the restart analysis. + + Load-stiffness effects are included in the supported elements for the real part of all loads at the + current configuration. All other load properties are included in the load vector of the elements. + + You can specify an unsymmetric matrix ( :ref:`nropt`,UNSYM) for the load-stiffness effects if + needed. + """ + command = f"SFCONTROL,{kcsys},{lcomp},{val1},{val2},{val3},{ktaper},{kuse},{karea},{kproj},{kfollow}" + return self.run(command, **kwargs) + + def sfcum( + self, lab: str = "", oper: str = "", fact: str = "", fact2: str = "", **kwargs + ): + r"""Specifies that surface loads are to be accumulated. - APDL Command: SFCUM + Mechanical APDL Command: `SFCUM `_ Parameters ---------- - lab - Valid surface load label. If ALL, use all appropriate labels. + lab : str + Valid surface load label. If ALL, use all appropriate labels. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above... _sfcum1: - oper + Thermal labels CONV and HFLUX are mutually exclusive. + + oper : str Accumulation key: - REPL - Subsequent values replace the previous values (default). + * ``REPL`` - Subsequent values replace the previous values (default). - ADD - Subsequent values are added to the previous values. + * ``ADD`` - Subsequent values are added to the previous values. - IGNO - Subsequent values are ignored. + * ``IGNO`` - Subsequent values are ignored. - fact - Scale factor for the first surface load value. A (blank) or '0' - entry defaults to 1.0. + fact : str + Scale factor for the first surface load value. A (blank) or '0' entry defaults to 1.0. - fact2 - Scale factor for the second surface load value. A (blank) or '0' - entry defaults to 1.0. + fact2 : str + Scale factor for the second surface load value. A (blank) or '0' entry defaults to 1.0. Notes ----- - Allows repeated surface loads (pressure, convection, etc.) to be - replaced, added, or ignored. Surface loads are applied with the SF, - SFE, and SFBEAM commands. Issue the SFELIST command to list the - surface loads. The operations occur when the next surface load - specifications are defined. For example, issuing the SF command with a - pressure value of 25 after a previous SF command with a pressure value - of 20 causes the current value of that pressure to be 45 with the add - operation, 25 with the replace operation, or 20 with the ignore - operation. All new pressures applied with SF after the ignore - operation will be ignored, even if no current pressure exists on that - surface. - - Scale factors are also available to multiply the next value before the - add or replace operation. A scale factor of 2.0 with the previous - "add" example results in a pressure of 70. Scale factors are applied - even if no previous values exist. Issue SFCUM,STAT to show the current - label, operation, and scale factors. Solid model boundary conditions - are not affected by this command, but boundary conditions on the FE - model are affected. - - Note:: : The FE boundary conditions may still be overwritten by - existing solid model boundary conditions if a subsequent boundary - condition transfer occurs. - - SFCUM does not work for tabular boundary conditions. + + .. _SFCUM_notes: + + Allows repeated surface loads (pressure, convection, etc.) to be replaced, added, or ignored. + Surface loads are applied with the :ref:`sf`, :ref:`sfe`, and :ref:`sfbeam` commands. Issue the + :ref:`sfelist` command to list the surface loads. The operations occur when the next surface load + specifications are defined. For example, issuing the :ref:`sf` command with a pressure value of 25 + after a previous :ref:`sf` command with a pressure value of 20 causes the current value of that + pressure to be 45 with the add operation, 25 with the replace operation, or 20 with the ignore + operation. All new pressures applied with :ref:`sf` after the ignore operation will be ignored, even + if no current pressure exists on that surface. + + Scale factors are also available to multiply the next value before the add or replace operation. A + scale factor of 2.0 with the previous "add" example results in a pressure of 70. Scale factors are + applied even if no previous values exist. Issue :ref:`sfcum`,STAT to show the current label, + operation, and scale factors. Solid model boundary conditions are not affected by this command, but + boundary conditions on the FE model are affected. + + The FE boundary conditions may still be overwritten by existing solid model boundary conditions if a + subsequent boundary condition transfer occurs. + + :ref:`sfcum` does not work for tabular boundary conditions. This command is also valid in PREP7. """ command = f"SFCUM,{lab},{oper},{fact},{fact2}" return self.run(command, **kwargs) - def sfdele(self, nlist="", lab="", **kwargs): - """Deletes surface loads. + def sfdele(self, nlist: str = "", lab: str = "", **kwargs): + r"""Deletes surface loads. - APDL Command: SFDELE + Mechanical APDL Command: `SFDELE `_ Parameters ---------- - nlist + nlist : str Label defining where to find the list of nodes: - ALL - Use all selected nodes [NSEL]. If P, use graphical picking in GUI. A - component label may be substituted for Nlist. + * ``ALL`` - Use all selected nodes ( :ref:`nsel` ). A component label may be substituted for + ``Nlist``. - lab - Valid surface load label. If ALL, use all appropriate labels. See - the SF command for labels. + lab : str + Valid surface load label. If ALL, use all appropriate labels. See the :ref:`sf` command for + labels. Notes ----- - Deletes surface loads as applied with the SF command. Loads are - deleted only for the specified nodes on external faces of selected area - and volume elements. For shell elements, if the specified nodes - include face one (which is usually the bottom face) along with other - faces (such as edges), only the loads on face one will be deleted. The - element faces are determined from the list of selected nodes as - described for the SF command. See the SFEDELE command for deleting - loads explicitly by element faces. + + .. _SFDELE_notes: + + Deletes surface loads as applied via :ref:`sf`. Loads are deleted only for the specified nodes on + external faces of selected area and volume elements. For shell elements, if the specified nodes + include face one (which is usually the bottom face) along with other faces (such as edges), only the + loads on face one will be deleted. The element faces are determined from the list of selected nodes + as described for :ref:`sf`. Issue :ref:`sfedele` to delete loads explicitly by element faces. This command is also valid in PREP7. """ @@ -257,330 +775,619 @@ def sfdele(self, nlist="", lab="", **kwargs): def sfe( self, - elem="", - lkey="", - lab="", - kval="", - val1="", - val2="", - val3="", - val4="", + elem: str = "", + lkey: str = "", + lab: str = "", + kval: int | str = "", + value1: str = "", + value2: str = "", + value3: str = "", + value4: str = "", + meshflag: str = "", **kwargs, ): - """Specifies surface loads on elements. + r"""Defines surface loads on elements. - APDL Command: SFE + Mechanical APDL Command: `SFE `_ Parameters ---------- - elem - Element to which surface load applies. If ALL, apply load to all - selected elements [ESEL]. If Elem = P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). A component name may be substituted for Elem. - - lkey - Load key or face number associated with surface load (defaults to - 1). Load keys (1,2,3, etc.) are listed under "Surface Loads" in - the input data table for each element type in the Element - Reference. - - lab - Valid surface load label. Load labels are listed under "Surface - Loads" in the input table for each element type in the Element - Reference. - - kval - Value key. If Lab = PRES: - - 0 or 1 - VAL1 through VAL4 are used as real components of pressures. - - 2 - VAL1 through VAL4 are used as imaginary components of pressures. - - val1 - First surface load value (typically at the first node of the face) - or the name of a table for specifying tabular boundary conditions. - Face nodes are listed in the order given for "Surface Loads" in the - input data table for each element type in the Element Reference. - For example, for SOLID185, the item 1-JILK associates LKEY = 1 - (face 1) with nodes J, I, L, and K. Surface load value VAL1 then - applies to node J of face 1. To specify a table, enclose the table - name in percent signs (%), e.g., %tabname%. Use the ``*DIM`` command - to define a table. Only one table can be specified, and it must be - specified in the VAL1 position; tables specified in the VAL2, VAL3, - or VAL4 positions will be ignored. VAL2 applies to node I, etc. + elem : str + Element to which surface load applies. If ALL, apply load to 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 be substituted for ``Elem``. + + lkey : str + Load key or face number associated with surface load (defaults to 1). Load keys (1,2,3, etc.) + are listed under "Surface Loads" in the input data table for each element type in the `Element + Reference `_. + + If you issue :ref:`sfcontrol` before :ref:`sfe`, ``LKEY`` is the face number for `supported + structural solid and shell elements + `_. + + lab : str + Valid surface load label. Load labels are listed under "Surface Loads" in the input table for + each element type in the `Element Reference + `_. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _sfe1: + + Thermal labels CONV and HFLUX are mutually exclusive. + + .. _sfe2: + + For an acoustic analysis, apply the fluid-structure interaction flag (Label = FSI) to only the + ``FLUID29``, ``FLUID30``, ``FLUID220``, and ``FLUID221`` elements. + + .. _sfe4: + + When a load vector exists for a thermal superelement, it must be applied and have a scale factor + of 1 ( :ref:`sfe`,,,SELV,,1). + + kval : int or str + Value key. If ``Lab`` = PRES: + + * ``0 or 1`` - ``VALUE1`` through ``VALUE4`` are used as real components of pressures. + + * ``2`` - ``VALUE1`` through ``VALUE4`` are used as imaginary components of pressures. + + Value key. If ``Lab`` = CONV: + + * ``0 or 1`` - For thermal analyses, ``VALUE1`` through ``VALUE4`` are used as the film + coefficients. + + * ``2`` - For thermal analyses, ``VALUE1`` through ``VALUE4`` are the bulk temperatures. + + * ``3`` - ``VALUE1`` through ``VALUE4`` are used as film effectiveness. + + * ``4`` - ``VALUE1`` through ``VALUE4`` are used as free stream temperature. + + Value key. If ``Lab`` = RAD: + + * ``0 or 1`` - ``VALUE1`` through ``VALUE4`` are used as the emissivities. + + * ``2`` - ``VALUE1`` through ``VALUE4`` are ambient temperatures. + + Value key. If ``Lab`` = RDSF: + + * ``0 or 1`` - ``VALUE1`` is the emissivity value between 0 and 1. + + * ``2`` - ``VALUE1`` is the enclosure number. + + Value key. If ``Lab`` = IMPD: + + * ``0 or 1`` - For acoustic harmonic analyses, VALUE1 through VALUE4 are used as the real part of + the impedance. + + * ``2`` - For acoustic harmonic analyses, VALUE1 through VALUE4 are used as the imaginary part of + the impedance. + + Value key. If ``Lab`` = SHLD: + + * ``0 or 1`` - For acoustic analyses, ``VALUE1`` through ``VALUE4`` are used as the normal velocity + (harmonic) or normal acceleration (transient). + + * ``2`` - For acoustic analyses, ``VALUE1`` through ``VALUE4`` are used as the phase angle for + harmonic response analyses. + + Value key. If ``Lab`` = ATTN: + + * ``0 or 1`` - For acoustic analyses, ``VALUE1`` through ``VALUE4`` are used as the absorption + coefficient of the surface. + + * ``2`` - For acoustic analyses, ``VALUE1`` through ``VALUE4`` are used as the transmission loss + (dB) of the coupled wall in an energy diffusion solution for room acoustics. + + Value key. If ``Lab`` = SELV: + + * ``0 or 1`` - ``VALUE1`` is the multiplier on real load vector ``LKEY``. + + * ``2`` - ``VALUE1`` is the multiplier on imaginary load vector ``LKEY``. + + If only one set of data is supplied, the other set of data defaults to previously specified values + (or zero if not previously specified) in the all of the following cases: + + * Emissivities are supplied and ``Lab`` = RAD + + * Temperatures are supplied and ``Lab`` = RAD + + * Temperatures are supplied and ``Lab`` = CONV + + * Film coefficients are supplied and ``Lab`` = CONV + + * Normal velocity/acceleration for acoustics is supplied and ``Lab`` = SHLD + + * Phase angle for acoustics is supplied and ``Lab`` = SHLD + + value1 : str + First surface load value (typically at the first node of the face), or the name of a table for + specifying tabular boundary conditions. + + Face nodes are listed in the order given for **Surface Loads** in the input data table for each element type in the `Element Reference `_. For example, for ``SOLID185``, the item 1-JILK associates ``LKEY`` = 1 (face 1) with nodes J, I, L, and K. Surface load value ``VALUE1`` then applies to node J of face 1. To specify a table, enclose the table name in percent signs (%), for example, ``tabname``. Use the :ref:`dim` command to define a table. Only one table can be specified, and it must be specified in the ``VALUE1`` position; tables specified in the ``VALUE2``, ``VALUE3``, or ``VALUE4`` positions are ignored. ``VALUE2`` applies to node I, etc. + + If ``Lab`` = PRES and ``KVAL`` = 2, this value is the imaginary pressure component, used by the following supported elements: + + * Surface elements: ``SURF153``, ``SURF154`` and ``SURF159``. + + * Solid and solid-shell elements: ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, + ``SOLID187``, ``SOLSH190``, and ``SOLID285``. + + * Shell elements: ``SHELL181``, ``SHELL281``, ``SHELL208``, and ``SHELL209``. + + * Coupled-field elements with structural degrees of freedom: ``PLANE222``, ``PLANE223``, + ``SOLID225``, ``SOLID226``, and ``SOLID227``. + + If ``Lab`` = CONV, ``KVAL`` = 0 or 1, and ``VALUE1`` = - ``N``, the film coefficient is assumed to + be a function of temperature and is determined from the HF property table for material ``N`` ( + :ref:`mp` ). (See the :ref:`scopt` command for a way to override this option and use - ``N`` as the + film coefficient.) The temperature used to evaluate the film coefficient is usually the average + between the bulk and wall temperatures, but may be user-defined for some elements. + + If ``Lab`` = CONV, ``KVAL`` = 2, ``VALUE1`` specifies the bulk temperature. If :ref:`kbc`,0 has been + issued for ramped loads, the bulk temperature is ramped from the value defined by :ref:`tunif` to + that specified on ``VALUE1`` (for the first loadstep). If a table name is specified for ``VALUE1``, + the :ref:`kbc` command is ignored and tabular values are used. + + If ``Lab`` = PORT, ``VALUE1`` is a port number representing a waveguide port. The port number must + be an integer between 1 and 50. For an acoustic 2×2 transfer admittance matrix, the port number can + be any positive integer. The smaller port number corresponds to port 1 of the 2×2 transfer + admittance matrix, and the greater port number corresponds to port 2. If one port of the transfer + admittance matrix is connecting to the acoustic-structural interaction interface, the port number + corresponds to port 2 of the transfer admittance matrix. A pair of ports of the 2×2 transfer + admittance matrix must be defined in the same element. + + If ``Lab`` = RDSF, ``KVAL`` = 0 or 1, and ``VALUE1`` = - ``N``, the emissivity is assumed to be a + function of the temperature, and is determined from the EMISS property table for material ``N`` ( + :ref:`mp` ). The material ``N`` does not need to correlate with the underlying solid thermal + elements. If ``Lab`` = RDSF, ``KVAL`` = 2, and ``VALUE1`` is negative, radiation direction is + reversed and will occur inside the element for the flagged radiation surfaces. + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL-to-CFX analysis, ``VALUE1`` is not used. + + If ``Lab`` = SELV, ``VALUE1`` represents the scale factor (default = 0.0). + + If ``Lab`` = ATTN, ``VALUE1`` is the absorption coefficient. + + value2 : str + Surface load values at the second, third, and fourth nodes (if any) of the face. + + If all three values are blank, all default to ``VALUE1``, giving a constant load. Zero or other + blank values are used as zero. + + If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are magnitudes of the load, they are ignored if + ``VALUE1`` is a table. If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are any other values, they are + used even if ``VALUE1`` is a table (for example, the load direction for face 5 of ``SURF154`` ). + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL-to-CFX analysis, ``VALUE2`` is the surface + interface number (not available in the GUI). ``VALUE3`` and ``VALUE4`` are not used. + + value3 : str + Surface load values at the second, third, and fourth nodes (if any) of the face. + + If all three values are blank, all default to ``VALUE1``, giving a constant load. Zero or other + blank values are used as zero. + + If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are magnitudes of the load, they are ignored if + ``VALUE1`` is a table. If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are any other values, they are + used even if ``VALUE1`` is a table (for example, the load direction for face 5 of ``SURF154`` ). + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL-to-CFX analysis, ``VALUE2`` is the surface + interface number (not available in the GUI). ``VALUE3`` and ``VALUE4`` are not used. + + value4 : str + Surface load values at the second, third, and fourth nodes (if any) of the face. + + If all three values are blank, all default to ``VALUE1``, giving a constant load. Zero or other + blank values are used as zero. + + If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are magnitudes of the load, they are ignored if + ``VALUE1`` is a table. If ``VALUE2``, ``VALUE3``, or ``VALUE4`` are any other values, they are + used even if ``VALUE1`` is a table (for example, the load direction for face 5 of ``SURF154`` ). + + If ``Lab`` = FSIN in a unidirectional Mechanical APDL-to-CFX analysis, ``VALUE2`` is the surface + interface number (not available in the GUI). ``VALUE3`` and ``VALUE4`` are not used. + + meshflag : str + Specifies how to apply normal pressure loading on the mesh. Valid in a `nonlinear adaptivity + analysis `_ + when ``Lab`` = PRES and ``KVAL`` = 0 or 1. + + 0 - Pressure loading occurs on the current mesh (default). + + 1 - Pressure loading occurs on the initial mesh for nonlinear adaptivity. + + Notes + ----- + + .. _SFE_notes: + + :ref:`sfe` defines surface loads on selected elements. + + .. warning:: + + You cannot use SFE with the INFIN110or INFIN111elements without prior knowledge of element-face + orientation (that is, you must know which face is the exterior in order to flag it). Also, for + surface-effect elements SURF153and SURF154, use LKEYto enable tangential and other loads. For + supported structural solid and shell elements, issue SFCONTROL to define tangential and other + loads. + + :ref:`sfe` can apply tapered loads over the faces of most elements. + + You can use these related surface-load commands with :ref:`sfe` : + + * :ref:`sf` - Defines surface loads on nodes. + * :ref:`sfbeam` - For beam elements allowing lateral surface loads that can be offset from the + nodes, this command specifies the loads and offsets. + * :ref:`sfcontrol` - Applies general (normal, tangential, and other) surface loads to `supported + structural elements + `_. + * :ref:`sfcum` - Accumulates (adds) surface loads applied via :ref:`sfe`. + * :ref:`sfdele` - Delete loads applied via :ref:`sfe`. + * :ref:`sffun` - Applies loads from a node-vs.-value function. + * :ref:`sfgrad` - Applies an alternate tapered load. + + The :ref:`sfe` command can also define fluid-pressure-penetration loads ( ``Lab`` = PRES) at a + contact interface. For this type of load, ``LKEY`` = 1 is used to specify the normal pressure + values, ``LKEY`` = 3 is used to specify the tangential pressure values along the x direction of + :ref:`esys`, ``LKEY`` = 4 is used to specify the tangential pressure values along the y direction of + :ref:`esys`, and ``LKEY`` = 2 is used to specify starting points and penetrating points. See + `Applying Fluid Penetration Pressure + `_ + + Film effectiveness and free-stream temperatures specified via ``Lab`` = CONV are valid only for + ``SURF151`` and ``SURF152``. Film effectiveness must be between 0 and 1 and it defaults to 0. If + film effectiveness is applied, bulk temperature is ignored. When film effectiveness and free stream + temperatures are specified, the commands to specify a surface-load gradient ( :ref:`sfgrad` ) or + surface-load accumulation ( :ref:`sfcum` ) are not valid. For more information about film + effectiveness, see `Conduction, Convection, and Mass Transport (Advection) + `_ + + You can specify a table name only when using structural (PRES) and thermal (CONV [film coefficient, + bulk temperature, film effectiveness, and free stream temperature], HFLUX), diffusion flux (DFLUX), + surface emissivity and ambient temperature (RAD), impedance (IMPD), normal velocity or acceleration + (SHLD), absorption coefficient (ATTN), and substructure (SELV) surface load labels. + + When a tabular function load is applied to an element, the load will not vary according to the + positioning of the element in space. + + For cases where Lab=FSI, MXWF, FREE, and INF, VALUE is not needed. + + 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. + + This command is also valid in the PREP7 and :ref:`slashmap` processors. """ - command = f"SFE,{elem},{lkey},{lab},{kval},{val1},{val2},{val3},{val4}" + command = f"SFE,{elem},{lkey},{lab},{kval},{value1},{value2},{value3},{value4},{meshflag}" return self.run(command, **kwargs) - def sfedele(self, elem="", lkey="", lab="", **kwargs): - """Deletes surface loads from elements. + def sfedele( + self, elem: str = "", lkey: str = "", lab: str = "", lcomp: str = "", **kwargs + ): + r"""Deletes surface loads from elements. - APDL Command: SFEDELE + Mechanical APDL Command: `SFEDELE `_ Parameters ---------- - elem - Element to which surface load deletion applies. If ALL, delete - load from all selected elements [ESEL]. If ELEM = P, graphical - picking is enabled and all remaining command fields are ignored - (valid only in the GUI). A component name may be substituted for - ELEM. + elem : str + Element to which surface load deletion applies. If ALL, delete load from 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 be substituted for ``ELEM``. + + lkey : str + Load key associated with surface load (defaults to 1). If ALL, delete surface loads for all load + keys. If :ref:`sfcontrol` is issued for selected elements, this value is the face number. If + ALL, deletes the surface load based on ``Lcomp``. - lkey - Load key associated with surface load (defaults to 1). If ALL, - delete surface loads for all load keys. + lab : str + Surface load label. If ALL, use all appropriate labels. See :ref:`sfe` for valid labels. - lab - Valid surface load label. If ALL, use all appropriate labels. See - the SFE command for labels. + lcomp : str + Label of surface-load components. Valid when the surface load is defined via :ref:`sfcontrol`. + Valid labels are NORM, TANX, TAXY when ``KCSYS`` = 0, LOCX, LOCY, LOCZ when ``KCSYS`` = 1, and + USER when ``KCSYS`` = 2. ( ``KCSYS`` is specified when issuing :ref:`sfcontrol`.) If ALL, + deletes all component on the face defined by ``LKEY``. Notes ----- - Deletes surface loads from selected elements. See the SFDELE command - for an alternate surface load deletion capability based upon selected - nodes. + + .. _SFEDELE_notes: + + Deletes surface loads from selected elements. See the :ref:`sfdele` command for an alternate surface + load deletion capability based upon selected nodes. This command is also valid in PREP7. """ - command = f"SFEDELE,{elem},{lkey},{lab}" + command = f"SFEDELE,{elem},{lkey},{lab},{lcomp}" return self.run(command, **kwargs) - def sfelist(self, elem="", lab="", **kwargs): - """Lists the surface loads for elements. + def sfelist(self, elem: str = "", lab: str = "", **kwargs): + r"""Lists the surface loads for elements. - APDL Command: SFELIST + Mechanical APDL Command: `SFELIST `_ Parameters ---------- - elem - Element at which surface load is to be listed. If ALL (or blank), - list loads for all selected elements [ESEL]. If ELEM = P, - graphical picking is enabled and all remaining command fields are - ignored (valid only in the GUI). A component name may be - substituted for ELEM. - - lab - Valid surface load label. If ALL (or blank), use all appropriate - labels. + elem : str + Element at which surface load is to be listed. If ALL (or blank), list loads for 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 be substituted for + ``ELEM``. + + lab : str + Valid surface load label. If ALL (or blank), use all appropriate labels. See the :ref:`sfe` + command for labels. Notes ----- - The surface loads listed correspond to the current database values. The - database is not updated for surface loads in POST1. Surface loads - specified in tabular form, however, do list their values corresponding - to the current results set in POST1. - - For SURF151 or SURF152 elements with an extra node for radiation and/or - convection calculations (KEYOPT(5) = 1), the bulk temperature listed is - the temperature of the extra node. If the thermal solution does not - converge, the extra node temperature is not available for listing. - - Film effectiveness and free stream temperatures specified by the SFE - command (Lab = CONV) can only be listed by this command. The command - lists film coefficients and bulk temperatures first and then film - effectiveness and free stream temperatures below those values. - - Distributed ANSYS Restriction: In Distributed ANSYS within the SOLUTION - processor, SFELIST support is not available for elements SURF151 and - SURF152 when surface loading is applied via extra nodes (KEYOPT(5 > 0). - If the command is issued under these circumstances, the resulting - surface loads shown are not reliable. + + .. _SFELIST_notes: + + The surface loads listed correspond to the current database values. The database is not updated for + surface loads in POST1. Surface loads specified in tabular form, however, do list their values + corresponding to the current results set in POST1. + + For ``SURF151`` or ``SURF152`` elements with an extra node for radiation and/or convection + calculations (KEYOPT(5) = 1), the bulk temperature listed is the temperature of the extra node. If + the thermal solution does not converge, the extra node temperature is not available for listing. + + Film effectiveness and free stream temperatures specified by the :ref:`sfe` command ( ``Lab`` = + CONV) can only be listed by this command. The command lists film coefficients and bulk temperatures + first and then film effectiveness and free stream temperatures below those values. + + Distributed-Memory Parallel (DMP) Restriction In a DMP analysis within the SOLUTION processor, + :ref:`sfelist` support is not available for + elements ``SURF151`` and ``SURF152`` when surface loading is applied via extra nodes (KEYOPT(5 > 0). + If the command is issued under these circumstances, the resulting surface loads shown are not + reliable. This command is valid in any processor. """ command = f"SFELIST,{elem},{lab}" return self.run(command, **kwargs) - def sffun(self, lab="", par="", par2="", **kwargs): - """Specifies a varying surface load. + def sffun(self, lab: str = "", par: str = "", par2: str = "", **kwargs): + r"""Specifies a varying surface load. - APDL Command: SFFUN + Mechanical APDL Command: `SFFUN `_ Parameters ---------- - lab - Valid surface load label. Load labels are listed under "Surface - Loads" in the input table for each element type in the Element - Reference. Issue SFFUN,STATUS to list current command settings. + lab : str + Valid surface load label. Load labels are listed under "Surface Loads" in the input table for + each element type in the `Element Reference + `_. Issue + :ref:`sffun`,STATUS to list current command settings. - par - Parameter containing list of surface load values. If Lab = CONV, - values are typically the film coefficients and Par2 values (below) - are typically the bulk temperatures. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above... _sffun1: - par2 - Parameter containing list of second surface load values (if any). - If Lab = CONV, the Par2 values are typically the bulk temperatures. - Par2 is not used for other surface load labels. + Thermal labels CONV and HFLUX are mutually exclusive. + + par : str + Parameter containing list of surface load values. If ``Lab`` = CONV, values are typically the + film coefficients and ``Par2`` values (below) are typically the bulk temperatures. + + par2 : str + Parameter containing list of second surface load values (if any). If ``Lab`` = CONV, the + ``Par2`` values are typically the bulk temperatures. ``Par2`` is not used for other surface load + labels. Notes ----- - Specifies a surface load "function" to be used when the SF or SFE - command is issued. The function is supplied through an array parameter - vector which contains nodal surface load values. Node numbers are - implied from the sequential location in the array parameter. For - example, a value in location 11 applies to node 11. The element faces - are determined from the implied list of nodes when the SF or SFE - command is issued. Zero values should be supplied for nodes that have - no load. A tapered load value may be applied over the element face. - These loads are in addition to any loads that are also specified with - the SF or SFE commands. Issue SFFUN (with blank remaining fields) to - remove this specification. Issue SFFUN,STATUS to list current - settings. - - Starting array element numbers must be defined for each array parameter - vector. For example, SFFUN,CONV,A(1,1),A(1,2) reads the first and - second columns of array A (starting with the first array element of - each column) and associates the values with the nodes. Operations - continue on successive column array elements until the end of the - column. Another example to show the order of the commands: - - SFFUN does not work for tabular boundary conditions. + + .. _SFFUN_notes: + + Specifies a surface load "function" to be used when the :ref:`sf` or :ref:`sfe` command is issued. + The function is supplied through an array parameter vector which contains nodal surface load values. + Node numbers are implied from the sequential location in the array parameter. For example, a value + in location 11 applies to node 11. The element faces are determined from the implied list of nodes + when the :ref:`sf` or :ref:`sfe` command is issued. Zero values should be supplied for nodes that + have no load. A tapered load value may be applied over the element face. These loads are in addition + to any loads that are also specified with the :ref:`sf` or :ref:`sfe` commands. Issue :ref:`sffun` + (with blank remaining fields) to remove this specification. Issue :ref:`sffun`,STATUS to list + current settings. + + Starting array element numbers must be defined for each array parameter vector. For example, + :ref:`sffun`,CONV,A(1,1),A(1,2) reads the first and second columns of array A (starting with the + first array element of each column) and associates the values with the nodes. Operations continue on + successive column array elements until the end of the column. Another example to show the order of + the commands: + + .. code:: apdl + + *dim,nodepres,array,2 + nodepres(1)=11,12 + /prep7 + et,1,42 + n,1 + n,2,1 + n,3,1,1 + n,4,,1 + e,1,2,3,4 + sfe,1,1,pres,1,3 + sfelist ! expected answer: 3 at both nodes 1 and 2 + sfedel,all,pres,all + sffun,pres, nodepres(1) + sfe,1,1,pres,1,5 + sfelist ! expected answer: 5+11=16 at node 1, 5+12=17 at node 2 + fini + + :ref:`sffun` does not work for tabular boundary conditions. + + 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. This command is also valid in PREP7. """ command = f"SFFUN,{lab},{par},{par2}" return self.run(command, **kwargs) - def sfgrad(self, lab="", slkcn="", sldir="", slzer="", slope="", **kwargs): - """Specifies a gradient (slope) for surface loads. + def sfgrad( + self, + lab: str = "", + slkcn: str = "", + sldir: str = "", + slzer: str = "", + slope: str = "", + **kwargs, + ): + r"""Specifies a gradient (slope) for surface loads. - APDL Command: SFGRAD + Mechanical APDL Command: `SFGRAD `_ Parameters ---------- - lab - Valid surface load label. Load labels are listed under "Surface - Loads" in the input table for each element type in the Element - Reference. + lab : str + Valid surface load label. Load labels are listed under "Surface Loads" in the input table for + each element type in the `Element Reference + `_. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above... _sfgrad1: - slkcn - Reference number of slope coordinate system (used with Sldir and - SLZER to determine COORD). Defaults to 0 (the global Cartesian - coordinate system). + Thermal labels CONV and HFLUX are mutually exclusive. - sldir - Slope direction in coordinate system SLKCN: + slkcn : str + Reference number of slope coordinate system (used with ``Sldir`` and ``SLZER`` to determine + COORD). Defaults to 0 (the global Cartesian coordinate system). - X - Slope is along X direction (default). Interpreted as R direction for non- - Cartesian coordinate systems. + sldir : str + Slope direction in coordinate system ``SLKCN`` : - Y - Slope is along Y direction. Interpreted as θ direction for non-Cartesian - coordinate systems. + * ``X`` - Slope is along X direction (default). Interpreted as R direction for non-Cartesian + coordinate systems. - Z - Slope is along Z direction. Interpreted as Φ direction for spherical or - toroidal coordinate systems. + * ``Y`` - Slope is along Y direction. Interpreted as θ direction for non-Cartesian coordinate + systems. - slzer - Coordinate location (degrees for angular input) where slope - contribution is zero (CVALUE = VALUE). Allows the slope - contribution to be shifted along the slope direction. For angular - input, SLZER should be between ±180° if the singularity [CSCIR] is - at 180° and should be between 0° and 360° if the singularity is at - 0°. + * ``Z`` - Slope is along Z direction. Interpreted as Φ direction for spherical or toroidal + coordinate systems. - slope + slzer : str + Coordinate location (degrees for angular input) where slope contribution is zero (CVALUE = + VALUE). Allows the slope contribution to be shifted along the slope direction. For angular + input, ``SLZER`` should be between ±180° if the singularity ( :ref:`cscir` ) is at 180° and + should be between 0° and 360° if the singularity is at 0°. + + slope : str Slope value (load per unit length or per degree). Notes ----- - Specifies a gradient (slope) for surface loads. All surface loads - issued with the SF, SFE, SFL, or SFA commands while this specification - is active will have this gradient applied (for complex pressures, only - the real component will be affected; for convections, only the bulk - temperature will be affected). The load value, CVALUE, calculated at - each node is: - - CVALUE = VALUE + (SLOPE X (COORD-SLZER)) - - where VALUE is the load value specified on the subsequent SF, SFE, SFL, - or SFA commands and COORD is the coordinate value (in the Sldir - direction of coordinate system SLKCN) of the node. Only one SFGRAD - specification may be active at a time (repeated use of this command - replaces the previous specification with the new specification). Issue - SFGRAD (with blank fields) to remove the specification. Issue - SFGRAD,STAT to show the current command status. The SFGRAD - specification (if active) is removed when the LSREAD (if any) command - is issued. - - SFGRAD does not work for tabular boundary conditions. + + .. _SFGRAD_notes: + + Specifies a gradient (slope) for surface loads. All surface loads issued with the :ref:`sf`, + :ref:`sfe`, :ref:`sfl`, or :ref:`sfa` commands while this specification is active will have this + gradient applied (for complex pressures, only the real component will be affected; for convections, + only the bulk temperature will be affected). The load value, CVALUE, calculated at each node is: + + CVALUE = VALUE + ( ``SLOPE`` X (COORD- ``SLZER`` )) + + where VALUE is the load value specified on the subsequent :ref:`sf`, :ref:`sfe`, :ref:`sfl`, or + :ref:`sfa` commands and COORD is the coordinate value (in the ``Sldir`` direction of coordinate + system ``SLKCN`` ) of the node. Only one :ref:`sfgrad` specification may be active at a time + (repeated use of this command replaces the previous specification with the new specification). Issue + :ref:`sfgrad` (with blank fields) to remove the specification. Issue :ref:`sfgrad`,STAT to show the + current command status. The :ref:`sfgrad` specification (if active) is removed when the + :ref:`lsread` (if any) command is issued. + + :ref:`sfgrad` does not work for tabular boundary conditions. + + 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. This command is also valid in PREP7. """ command = f"SFGRAD,{lab},{slkcn},{sldir},{slzer},{slope}" return self.run(command, **kwargs) - def sflist(self, node="", lab="", **kwargs): - """Lists surface loads. + def sflist(self, node: str = "", lab: str = "", **kwargs): + r"""Lists surface loads. - APDL Command: SFLIST + Mechanical APDL Command: `SFLIST `_ Parameters ---------- - node - Node at which surface load is to be listed. If ALL (or blank), - list for all selected nodes [NSEL]. If NODE = P, graphical picking - is enabled and all remaining command fields are ignored (valid only - in the GUI). A component name may be substituted for NODE. - - lab - Valid surface load label. If ALL (or blank), use all appropriate - labels. + node : str + Node at which surface load is to be listed. If ALL (or blank), list for all selected nodes ( + :ref:`nsel` ). If ``NODE`` = P, graphical picking is enabled and all remaining command fields + are ignored (valid only in the GUI). A component name may be substituted for ``NODE``. + + lab : str + Valid surface load label. If ALL (or blank), use all appropriate labels. See the :ref:`sf` + command for labels Notes ----- - Lists the surface loads as applied with the SF command. Loads are - listed only for the specified nodes on external faces of selected area - and volume elements. Use SFELIST for line elements. The surface loads - listed correspond to the current database values. The database is not - updated for surface loads in POST1. Surface loads specified in tabular - form, however, do list their values corresponding to the current - results set in POST1. - - For SURF151 or SURF152 elements with an extra node for radiation and/or - convection calculations (KEYOPT(5) = 1), the bulk temperature listed is - the temperature of the extra node. If the thermal solution does not - converge, the extra node temperature is not available for listing. + + .. _SFLIST_notes: + + Lists the surface loads as applied with the :ref:`sf` command. Loads are listed only for the + specified nodes on external faces of selected area and volume elements. Use :ref:`sfelist` for line + elements. The surface loads listed correspond to the current database values. The database is not + updated for surface loads in POST1. Surface loads specified in tabular form, however, do list their + values corresponding to the current results set in POST1. + + For ``SURF151`` or ``SURF152`` elements with an extra node for radiation and/or convection + calculations (KEYOPT(5) = 1), the bulk temperature listed is the temperature of the extra node. If + the thermal solution does not converge, the extra node temperature is not available for listing. This command is valid in any processor. """ command = f"SFLIST,{node},{lab}" return self.run(command, **kwargs) - def sfscale(self, lab="", fact="", fact2="", **kwargs): - """Scales surface loads on elements. + def sfscale(self, lab: str = "", fact: str = "", fact2: str = "", **kwargs): + r"""Scales surface loads on elements. - APDL Command: SFSCALE + Mechanical APDL Command: `SFSCALE `_ Parameters ---------- - lab - Valid surface load label. If ALL, use all appropriate labels. + lab : str + Valid surface load label. If ALL, use all appropriate labels. - fact - Scale factor for the first surface load value. Zero (or blank) - defaults to 1.0. Use a small number for a zero scale factor. + This command contains some tables and extra information which can be inspected in the original + documentation pointed above... _sfscale1: - fact2 - Scale factor for the second surface load value. Zero (or blank) - defaults to 1.0. Use a small number for a zero scale factor. + Thermal labels CONV and HFLUX are mutually exclusive. + + fact : str + Scale factor for the first surface load value. Zero (or blank) defaults to 1.0. Use a small + number for a zero scale factor. + + fact2 : str + Scale factor for the second surface load value. Zero (or blank) defaults to 1.0. Use a small + number for a zero scale factor. Notes ----- - Scales surface loads (pressure, convection, etc.) in the database on - the selected elements. Surface loads are applied with the SF, SFE, or - SFBEAM commands. Issue the SFELIST command to list the surface loads. - Solid model boundary conditions are not scaled by this command, but - boundary conditions on the FE model are scaled. - Note:: : Such scaled FE boundary conditions may still be overwritten by - unscaled solid model boundary conditions if a subsequent boundary - condition transfer occurs. + .. _SFSCALE_notes: + + Scales surface loads (pressure, convection, etc.) in the database on the selected elements. Surface + loads are applied with the :ref:`sf`, :ref:`sfe`, or :ref:`sfbeam` commands. Issue the + :ref:`sfelist` command to list the surface loads. Solid model boundary conditions are not scaled by + this command, but boundary conditions on the FE model are scaled. + + Such scaled FE boundary conditions may still be overwritten by unscaled solid model boundary + conditions if a subsequent boundary condition transfer occurs. - SFSCALE does not work for tabular boundary conditions. + :ref:`sfscale` does not work for tabular boundary conditions. - This command is also valid in PREP7 and in the /MAP processor. + This command is also valid in PREP7 and in the :ref:`slashmap` processor. """ command = f"SFSCALE,{lab},{fact},{fact2}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/gap_conditions.py b/src/ansys/mapdl/core/_commands/solution/gap_conditions.py deleted file mode 100644 index 0cfe0a5bb34..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/gap_conditions.py +++ /dev/null @@ -1,203 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class GapConditions: - def gp(self, node1="", node2="", lab="", stif="", gap="", damp="", **kwargs): - """Defines a gap condition for transient analyses. - - APDL Command: GP - - Parameters - ---------- - node1 - Node I of gap. If NODE1 = P, graphical picking is enabled and all - remaining command fields are ignored (valid only in the GUI). - - node2 - 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 - Direction of gap action in the nodal coordinate system (implied - from the following force labels): FX, FY, FZ, MX, MY, MZ. - - stif - Stiffness (Force/Length) of closed gap (may be positive or - negative). - - gap - 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 - Damping coefficient (``Force*Time/Length``) of closed gap using pseudo - velocity (Newmark finite difference expansion scheme). - - Notes - ----- - Defines a gap condition for the mode superposition transient analysis - (ANTYPE,TRANS with 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 GP command for additional gap conditions. Gaps are numbered - sequentially as input. - - Note:: : 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. - - 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 GP - command; i.e., 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 [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; i.e., a gap - condition connecting two nodes will act differently depending upon - which node is specified first on the GP command. For example, for Node - 1 at X = 0.0, Node 2 at X = 0.1, 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 UJ - UI - + GAP) is negative. UJ is the displacement of node J, UI 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 GPLIST command to list gap conditions and the GPDELE command to - delete gap conditions. - - This command is also valid in PREP7. - """ - command = f"GP,{node1},{node2},{lab},{stif},{gap},{damp}" - return self.run(command, **kwargs) - - def gpdele(self, gap1="", gap2="", ginc="", **kwargs): - """Deletes gap conditions. - - APDL Command: GPDELE - - Parameters - ---------- - gap1, gap2, ginc - Delete gap conditions from GAP1 to GAP2 (defaults to GAP1) in steps - of GINC (defaults to 1). - - Notes - ----- - Deletes gap conditions defined with the 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. - """ - command = f"GPDELE,{gap1},{gap2},{ginc}" - return self.run(command, **kwargs) - - def gplist(self, gap1="", gap2="", ginc="", **kwargs): - """Lists the gap conditions. - - APDL Command: GPLIST - - Parameters - ---------- - gap1, gap2, ginc - 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 - ----- - This command is valid in any processor. - """ - command = f"GPLIST,{gap1},{gap2},{ginc}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/inertia.py b/src/ansys/mapdl/core/_commands/solution/inertia.py index f79e72af263..ad54edf0ff4 100644 --- a/src/ansys/mapdl/core/_commands/solution/inertia.py +++ b/src/ansys/mapdl/core/_commands/solution/inertia.py @@ -22,294 +22,523 @@ class Inertia: - def acel(self, acel_x="", acel_y="", acel_z="", **kwargs): - """Specifies the linear acceleration of the global Cartesian reference - APDL Command: ACEL - frame for the analysis. + def acel(self, acel_x: str = "", acel_y: str = "", acel_z: str = "", **kwargs): + r"""Specifies the linear acceleration of the global Cartesian reference frame for the analysis. + + Mechanical APDL Command: `ACEL `_ Parameters ---------- - acel_x, acel_y, acel_z - Linear acceleration of the reference frame along global Cartesian - X, Y, and Z axes, respectively. + acel_x : str + Linear acceleration of the reference frame along global Cartesian X, Y, and Z axes, + respectively. + + acel_y : str + Linear acceleration of the reference frame along global Cartesian X, Y, and Z axes, + respectively. + + acel_z : str + Linear acceleration of the reference frame along global Cartesian X, Y, and Z axes, + respectively. Notes ----- - In the absence of any other loads or supports, the acceleration of the - structure in each of the global Cartesian (X, Y, and Z) axes would be - equal in magnitude but opposite in sign to that applied in the ACEL - command. Thus, to simulate gravity (by using inertial effects), - accelerate the reference frame with an ACEL command in the direction - opposite to gravity. + + .. _ACEL_notes: + + In the absence of any other loads or supports, the acceleration of the structure in each of the + global Cartesian (X, Y, and Z) axes would be equal in magnitude but opposite in sign to that applied + in the :ref:`acel` command. Thus, to simulate gravity (by using inertial effects), accelerate the + reference frame with an :ref:`acel` command in the direction opposite to gravity. You can define the acceleration for the following analyses types: - Static (ANTYPE,STATIC) + * Static ( :ref:`antype`,STATIC) - Harmonic (ANTYPE,HARMIC), full or mode-superposition method + * Harmonic ( :ref:`antype`,HARMIC), full, `VT + `_ [ + :ref:`ACEL_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`ACEL_FN_VT_KRY` ], or mode-superposition [ :ref:`ACEL_mode-sup_LoadSupport` ] - Transient (ANTYPE,TRANS) + * Transient ( :ref:`antype`,TRANS), `full + `_ + or mode-superposition [ :ref:`ACEL_mode-sup_LoadSupport` ] - Substructure (ANTYPE,SUBSTR). + * Substructure ( :ref:`antype`,SUBSTR). - For all transient dynamic (ANTYPE,TRANS) analyses, accelerations are - combined with the element mass matrices to form a body force load - vector term. The element mass matrix may be formed from a mass input - constant or from a nonzero density (DENS) property, depending upon the - element type. + .. _ACEL_FN_VT_KRY: - For analysis type ANTYPE,HARMIC, the acceleration is assumed to be the - real component with a zero imaginary component. + Loads for VT and Krylov methods are supported as long as they are not: - Units of acceleration and mass must be consistent to give a product of - force units. + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) - The ACEL command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for ACEL_X, ACEL_Y, and ACEL_Z input - values (``*DIM``) as a function of both time and frequency for full - transient and harmonic analyses. + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). - Related commands for rotational effects are CMACEL, CGLOC, CGOMGA, - DCGOMG, DOMEGA, OMEGA, CMOMEGA, and CMDOMEGA. + .. _ACEL_mode-sup_LoadSupport: - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + 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. - This command is also valid in /PREP7. + For all transient dynamic ( :ref:`antype`,TRANS) analyses, accelerations are combined with the + element mass matrices to form a body-force load vector term. The element mass matrix may be formed + from a mass input constant or from a nonzero density (DENS) property, depending upon the element + type. - Examples - -------- - Set global y-acceleration to 9.81 + For analysis type :ref:`antype`,HARMIC, the acceleration is assumed to be the real component with a + zero imaginary component. + + Units of acceleration and mass must be consistent to give a product of force units. + + The :ref:`acel` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``ACEL_X``, ``ACEL_Y``, and ``ACEL_Z`` input values ( :ref:`dim` ) as a function + of both time and frequency for full transient and harmonic analyses. + + Related commands for rotational effects are :ref:`cmacel`, :ref:`cgloc`, :ref:`cgomga`, + :ref:`dcgomg`, :ref:`domega`, :ref:`omega`, :ref:`cmomega`, and :ref:`cmdomega`. - >>> mapdl.acel(acel_y=9.81) + See `Analysis Tools + `_ + + This command is also valid in :ref:`prep7`. """ command = f"ACEL,{acel_x},{acel_y},{acel_z}" return self.run(command, **kwargs) - def cgloc(self, xloc="", yloc="", zloc="", **kwargs): - """Specifies the origin location of the acceleration coordinate system. + def airl(self, nrb: int | str = "", rigid_calc: int | str = "", **kwargs): + r"""Specifies that automatic inertia relief calculations are to be performed. - APDL Command: CGLOC + Mechanical APDL Command: `AIRL `_ Parameters ---------- - xloc, yloc, zloc - Global Cartesian X, Y, and Z coordinates of the acceleration - coordinate system origin. + nrb : int or str + Number of rigid body modes in the model: + + * ``AUTO`` - Activate automatic inertia relief (default). The program automatically determines the + number of rigid body modes. + + * ``n`` - Activate automatic inertia relief with the assumption of ``n`` rigid body modes (1≤ ``n`` + ≤ 6). + + * ``0`` - Deactivate automatic inertia relief. + + rigid_calc : int or str + Method for computing the rigid body modes: + + * ``0`` - Use an eigensolver to compute rigid body modes (default). + + * ``1`` - Use the geometry to compute rigid body modes (valid only when ``NRB`` = AUTO). The + geometric rigid body vectors are calculated according to in `Participation Factors and Mode + Coefficients + `_ Notes ----- - Specifies the origin location of the acceleration coordinate system - with respect to the global Cartesian system. The axes of this - acceleration coordinate system are parallel to the global Cartesian - axes. - - A structure may be rotating about the global Cartesian origin [OMEGA, - DOMEGA], which may in turn be rotating about another point (the origin - of the acceleration coordinate system), introducing Coriolis effects. - The location of this point (relative to the global Cartesian origin) is - specified with this CGLOC command. For example, if Y is vertical and - the global system origin is at the surface of the earth while the - acceleration system origin is at the center of the earth, YLOC should - be -4000 miles (or equivalent) if the rotational effects of the earth - are to be included. The rotational velocity of the global Cartesian - system about this point is specified with the CGOMGA command, and the - rotational acceleration is specified with the DCGOMG command. - - The rotational velocities and accelerations are mainly intended to - include mass effects in a static (ANTYPE,STATIC) analysis. If used in - dynamic analyses, no coupling exists between the user input terms and - the time history response of the structure. See Acceleration Effect in - the Mechanical APDL Theory Reference for details. Related commands are - ACEL, CGOMGA, DCGOMG, DOMEGA, and OMEGA. - - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + + .. _AIRL_notes: + + The :ref:`airl` command activates automatic inertia relief for models having up to six rigid body + modes. This method is only valid for linear static analyses ( :ref:`antype`,STATIC). + + By default ( ``NRB`` = AUTO), the number of rigid body modes in the structure is automatically + determined. The static solution is altered so that the inertial effects factor into counterbalancing + the external loads. This method relies on calculation of the rigid body modes using either an + eigensolver ( ``RIGID_CALC`` = 0, which is the default) or the model geometry ( ``RIGID_CALC`` = 1). + + For the ``NRB`` = AUTO option, no supports should be defined. + + For a model that is partially constrained by design, you must set ``NRB`` to the number of rigid + body modes present in the structure and set ``RIGID_CALC`` = 0. The use of geometry ( ``RIGID_CALC`` + = 1) to compute the rigid-body modes of a partially constrained model is not supported. + + Loads may be input as usual. Displacements and stresses are calculated as usual. + + Use :ref:`irlist` to print inertia relief calculation results. The mass and moment of inertia + summary printed before the solution is accurate (because of the additional pre-calculations required + for inertia relief). See `Inertia Relief + `_ + `Including Inertia Relief Calculations + `_ This command is also valid in PREP7. + + **Example Usage** + Example command input for including automatic inertia relief calculations in a linear static + analysis is found in `Including Inertia Relief Calculations + `_ + """ + command = f"AIRL,{nrb},{rigid_calc}" + return self.run(command, **kwargs) + + def cgloc(self, xloc: str = "", yloc: str = "", zloc: str = "", **kwargs): + r"""Specifies the origin location of the acceleration coordinate system. + + Mechanical APDL Command: `CGLOC `_ + + Parameters + ---------- + xloc : str + Global Cartesian X, Y, and Z coordinates of the acceleration coordinate system origin. + + yloc : str + Global Cartesian X, Y, and Z coordinates of the acceleration coordinate system origin. + + zloc : str + Global Cartesian X, Y, and Z coordinates of the acceleration coordinate system origin. + + Notes + ----- + + .. _CGLOC_notes: + + Specifies the origin location of the acceleration coordinate system with respect to the global + Cartesian system. The axes of this acceleration coordinate system are parallel to the global + Cartesian axes. + + A structure may be rotating about the global Cartesian origin ( :ref:`omega`, :ref:`domega` ), which + may in turn be rotating about another point (the origin of the acceleration coordinate system), + introducing Coriolis effects. The location of this point (relative to the global Cartesian origin) + is specified with this :ref:`cgloc` command. For example, if Y is vertical and the global system + origin is at the surface of the earth while the acceleration system origin is at the center of the + earth, ``YLOC`` should be -4000 miles (or equivalent) if the rotational effects of the earth are to + be included. The rotational velocity of the global Cartesian system about this point is specified + with the :ref:`cgomga` command, and the rotational acceleration is specified with the :ref:`dcgomg` + command. + + The rotational velocities and accelerations are mainly intended to include mass effects in a static + ( :ref:`antype`,STATIC) analysis. If used in dynamic analyses, no coupling exists between the user + input terms and the time history response of the structure. See `Acceleration Effect + `_ :ref:`acel`, + :ref:`cgomga`, :ref:`dcgomg`, :ref:`domega`, and :ref:`omega`. + + See `Analysis Tools + `_ + + This command is also valid in PREP7. + + """ command = f"CGLOC,{xloc},{yloc},{zloc}" return self.run(command, **kwargs) - def cgomga(self, cgomx="", cgomy="", cgomz="", **kwargs): - """Specifies the rotational velocity of the global origin. + def cgomga(self, cgomx: str = "", cgomy: str = "", cgomz: str = "", **kwargs): + r"""Specifies the rotational velocity of the global origin. - APDL Command: CGOMGA + Mechanical APDL Command: `CGOMGA `_ Parameters ---------- - cgomx, cgomy, cgomz - Rotational velocity of the global origin about the acceleration - system X, Y, and Z axes. + cgomx : str + Rotational velocity of the global origin about the acceleration system X, Y, and Z axes. + + cgomy : str + Rotational velocity of the global origin about the acceleration system X, Y, and Z axes. + + cgomz : str + Rotational velocity of the global origin about the acceleration system X, Y, and Z axes. Notes ----- - Specifies the rotational velocity of the global origin about each of - the acceleration coordinate system axes. The location of the - acceleration coordinate system is defined with the CGLOC command. - Rotational velocities may be defined in analysis types ANTYPE,STATIC, - HARMIC (full or mode-superposition), TRANS (full or mode- - superposition), and SUBSTR. See Acceleration Effect in the Mechanical - APDL Theory Reference for details. Units are radians/time. Related - commands are ACEL, CGLOC, DCGOMG, DOMEGA, and OMEGA. - - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. - - The CGOMGA command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for CGOMGA_X, CGOMGA_Y, and CGOMGA_Z - input values (``*DIM``) for full transient and harmonic analyses. + + .. _CGOMGA_notes: + + Specifies the rotational velocity of the global origin about each of the acceleration coordinate + system axes. The location of the acceleration coordinate system is defined with the :ref:`cgloc` + command. Rotational velocities may be defined in these analysis types: + + * Static ( :ref:`antype`,STATIC) + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`CGOMGA_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`CGOMGA_FN_VT_KRY` ], or mode-superposition [ :ref:`CGOMGA_mode-sup_LoadSupport` ] + + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`CGOMGA_mode-sup_LoadSupport` ] + + * Substructuring ( :ref:`antype`,SUBSTR) + + * Modal ( :ref:`antype`,MODAL) + + .. _CGOMGA_FN_VT_KRY: + + Loads for VT and Krylov methods are supported as long as they are not: + + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) + + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). + + .. _CGOMGA_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. + + See `Acceleration Effect + `_ :ref:`acel`, + :ref:`cgloc`, :ref:`dcgomg`, :ref:`domega`, and :ref:`omega`. + + See `Analysis Tools + `_ + + The :ref:`cgomga` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``CGOMGA_X``, ``CGOMGA_Y``, and ``CGOMGA_Z`` input values ( :ref:`dim` ) for full + transient and harmonic analyses. This command is also valid in PREP7. """ command = f"CGOMGA,{cgomx},{cgomy},{cgomz}" return self.run(command, **kwargs) - def cmacel(self, cm_name="", cmacel_x="", cmacel_y="", cmacel_z="", **kwargs): - """Specifies the translational acceleration of an element component + def cmacel( + self, + cm_name: str = "", + cmacel_x: str = "", + cmacel_y: str = "", + cmacel_z: str = "", + **kwargs, + ): + r"""Specifies the translational acceleration of an element component - APDL Command: CMACEL + Mechanical APDL Command: `CMACEL `_ Parameters ---------- - cm_name + cm_name : str The name of the element component. - cmacel_x, cmacel_y, cmacel_z - Acceleration of the element component CM_NAME in the global - Cartesian X, Y, and Z axis directions, respectively. + cmacel_x : str + Acceleration of the element component ``CM_NAME`` in the global Cartesian X, Y, and Z axis + directions, respectively. + + cmacel_y : str + Acceleration of the element component ``CM_NAME`` in the global Cartesian X, Y, and Z axis + directions, respectively. + + cmacel_z : str + Acceleration of the element component ``CM_NAME`` in the global Cartesian X, Y, and Z axis + directions, respectively. Notes ----- - The CMACEL command specifies the translational acceleration of the - element component in each of the global Cartesian (X, Y, and Z) axis - directions. - Components for which you want to specify acceleration loading must - consist of elements only. The elements you use cannot be part of more - than one component, and elements that share nodes cannot exist in - different element components. You cannot apply the loading to an - assembly of element components. + .. _CMACEL_notes: + + The :ref:`cmacel` command specifies the translational acceleration of the element component in each + of the global Cartesian (X, Y, and Z) axis directions. - To simulate gravity (by using inertial effects), accelerate the - structure in the direction opposite to gravity. For example, apply a - positive CMACELY to simulate gravity acting in the negative Y - direction. Units are length/time2. + Components for which you want to specify acceleration loading must consist of elements only. The + elements you use cannot be part of more than one component, and elements that share nodes cannot + exist in different element components. You cannot apply the loading to an assembly of element + components. + + To simulate gravity (by using inertial effects), accelerate the structure in the direction opposite + to gravity. For example, apply a positive ``CMACELY`` to simulate gravity acting in the negative Y + direction. Units are length/time :sup:`2`. You can define the acceleration for the following analyses types: - Static (ANTYPE,STATIC) + * Static ( :ref:`antype`,STATIC) - Harmonic (ANTYPE,HARMIC), full or mode-superposition method + * Harmonic ( :ref:`antype`,HARMIC), full, `VT + `_ [ + :ref:`CMACEL_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`CMACEL_FN_VT_KRY` ], or mode-superposition [ :ref:`CMACEL_mode-sup_LVSCALE` ] method - Transient (ANTYPE,TRANS), full or mode-superposition method + * Transient ( :ref:`antype`,TRANS), `full + `_ + or mode-superposition [ :ref:`CMACEL_mode-sup_LVSCALE` ] method - Substructure (ANTYPE,SUBSTR) + * Substructure ( :ref:`antype`,SUBSTR) - Accelerations are combined with the element mass matrices to form a - body force load vector term. Units of acceleration and mass must be - consistent to give a product of force units. + .. _CMACEL_FN_VT_KRY: - In a modal 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 mode shape file, which you can apply via - the LVSCALE command. + Loads for VT and Krylov methods are supported as long as they are not: - The CMACEL command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for CMACEL_X, CMACEL_Y, and CMACEL_Z - input values (``*DIM``) as a function of both time and frequency for full - transient and harmonic analyses. + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) + + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). + + .. _CMACEL_mode-sup_LVSCALE: + + 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. - Related commands for inertia loads are ACEL, CGLOC, CGOMGA, DCGOMG, - DOMEGA, OMEGA, CMOMEGA, and CMDOMEGA. + Accelerations are combined with the element mass matrices to form a body-force load vector term. + Units of acceleration and mass must be consistent to give a product of force units. - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + The :ref:`cmacel` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``CMACEL_X``, ``CMACEL_Y``, and ``CMACEL_Z`` input values ( :ref:`dim` ) as a + function of both time and frequency for full transient and harmonic analyses. - This command is also valid in /PREP7. + Related commands for inertia loads are :ref:`acel`, :ref:`cgloc`, :ref:`cgomga`, :ref:`dcgomg`, + :ref:`domega`, :ref:`omega`, :ref:`cmomega`, and :ref:`cmdomega`. + + See `Analysis Tools + `_ + + This command is also valid in :ref:`prep7`. """ command = f"CMACEL,{cm_name},{cmacel_x},{cmacel_y},{cmacel_z}" return self.run(command, **kwargs) def cmdomega( self, - cm_name="", - domegax="", - domegay="", - domegaz="", - x1="", - y1="", - z1="", - x2="", - y2="", - z2="", + cm_name: str = "", + domegax: str = "", + domegay: str = "", + domegaz: str = "", + x1: str = "", + y1: str = "", + z1: str = "", + x2: str = "", + y2: str = "", + z2: str = "", **kwargs, ): - """Specifies the rotational acceleration of an element component about a + r"""Specifies the rotational acceleration of an element component about a user-defined rotational axis. - APDL Command: CMDOMEGA - user-defined rotational axis. + Mechanical APDL Command: `CMDOMEGA `_ Parameters ---------- - cm_name, + cm_name : str The name of the element component. - domegax, domegay, domegaz - If the X2, Y2, Z2 fields are not defined, DOMEGAX, DOMEGAY, and - DOMEGAZ specify the components of the rotational acceleration - vector in the global Cartesian X, Y, Z directions. + domegax : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``DOMEGAX``, ``DOMEGAY``, and ``DOMEGAZ`` + specify the components of the rotational acceleration vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``DOMEGAX`` is required. ``DOMEGAX`` + specifies the scalar rotational acceleration about the rotational axis. The rotational direction + of ``DOMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + domegay : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``DOMEGAX``, ``DOMEGAY``, and ``DOMEGAZ`` + specify the components of the rotational acceleration vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``DOMEGAX`` is required. ``DOMEGAX`` + specifies the scalar rotational acceleration about the rotational axis. The rotational direction + of ``DOMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + domegaz : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``DOMEGAX``, ``DOMEGAY``, and ``DOMEGAZ`` + specify the components of the rotational acceleration vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``DOMEGAX`` is required. ``DOMEGAX`` + specifies the scalar rotational acceleration about the rotational axis. The rotational direction + of ``DOMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + x1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + y1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + z1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + x2 : str + The coordinates of the end point of the rotational axis vector. - x1, y1, z1 - If the X2, Y2, Z2 fields are defined, X1, Y1, and Z1 define the - coordinates of the beginning point of the rotational axis vector. - Otherwise, X1, Y1, and Z1 are the coordinates of a point through - which the rotational axis passes. + y2 : str + The coordinates of the end point of the rotational axis vector. - x2, y2, z2 + z2 : str The coordinates of the end point of the rotational axis vector. Notes ----- - Specifies the rotational acceleration components DOMEGAX, DOMEGAY, and - DOMEGAZ of an element component CM_NAME about a user-defined rotational - axis. The rotational axis can be defined either as a vector passing - through a single point, or a vector connecting two points. - You can define the rotational acceleration and rotational axis with the - CMDOMEGA command for STATIC, HARMIC, TRANS, and SUBSTR analyses. - Rotational velocities are combined with the element mass matrices to - form a body force load vector term. Units are radians/time2. + .. _CMDOMEGA_notes: + + Specifies the rotational acceleration components ``DOMEGAX``, ``DOMEGAY``, and ``DOMEGAZ`` of an + element component ``CM_NAME`` about a user-defined rotational axis. The rotational axis can be + defined either as a vector passing through a single point, or a vector connecting two points. + + You can define the rotational acceleration and rotational axis with the :ref:`cmdomega` command for + these analyses: + + * Static ( :ref:`antype`,STATIC) + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`CMDOMEGA_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`CMDOMEGA_FN_VT_KRY` ], or mode-superposition [ :ref:`CMDOMEGA_mode-sup_LVSCALE` ] + + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`CMDOMEGA_mode-sup_LVSCALE` ] + + * Substructuring ( :ref:`antype`,SUBSTR) - The CMDOMEGA command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for CMDOMEGA_X, CMDOMEGA_Y, and - CMDOMEGA_Z input values (``*DIM``) for full transient and harmonic - analyses. + * Modal ( :ref:`antype`,MODAL) - Related commands are ACEL, CGLOC, CGLOC, OMEGA, CMOMEGA, DCGOMG, - DOMEGA. + .. _CMDOMEGA_FN_VT_KRY: - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + Loads for VT and Krylov methods are supported as long as they are not: - You can use the CMDOMEGA command in conjunction with any one of the - following two groups of commands, but not with both groups - simultaneously: + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) - Components for which you want to specify rotational loading must - consist of elements only. The elements you use cannot be part of more - than one component, and elements that share nodes cannot exist in - different element components. You cannot apply the loading to an - assembly of element components. + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). - In a modal 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 mode shape file, which you can apply via - the LVSCALE command. + .. _CMDOMEGA_mode-sup_LVSCALE: - See Acceleration Effect in the Mechanical APDL Theory Reference for - more information. + 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. + + Rotational velocities are combined with the element mass matrices to form a body force load vector + term. Units are radians/time :sup:`2`. + + The :ref:`cmdomega` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``DOMEGAX``, ``DOMEGAY``, and ``DOMEGAZ`` input values ( :ref:`dim` ) for full + transient and harmonic analyses. In this case, if the end point is specified ( ``X2``, ``Y2``, + ``Z2`` ), the rotational velocity axis must be along the global X-, Y-, or Z-axis. + + Related commands are :ref:`acel`, :ref:`cgloc`, :ref:`cgloc`, :ref:`omega`, :ref:`cmomega`, + :ref:`dcgomg`, :ref:`domega`. + + See `Analysis Tools + `_ + + You can use the :ref:`cmdomega` command in conjunction with any one of the following two groups of + commands, but not with both groups simultaneously: + + * GROUP ONE: :ref:`omega`, :ref:`domega`. + * GROUP TWO: :ref:`cgomga`, :ref:`dcgomg`, :ref:`cgloc`. + + Components for which you want to specify rotational loading must consist of elements only. The + elements you use cannot be part of more than one component, and elements that share nodes cannot + exist in different element components. You cannot apply the loading to an assembly of element + components. + + See `Acceleration Effect + `_ This command is also valid in PREP7. """ @@ -318,169 +547,278 @@ def cmdomega( def cmomega( self, - cm_name="", - omegax="", - omegay="", - omegaz="", - x1="", - y1="", - z1="", - x2="", - y2="", - z2="", + cm_name: str = "", + omegax: str = "", + omegay: str = "", + omegaz: str = "", + x1: str = "", + y1: str = "", + z1: str = "", + x2: str = "", + y2: str = "", + z2: str = "", **kwargs, ): - """Specifies the rotational velocity of an element component about a user- + r"""Specifies the rotational velocity of an element component about a user-defined rotational axis. - APDL Command: CMOMEGA - defined rotational axis. + Mechanical APDL Command: `CMOMEGA `_ Parameters ---------- - cm_name + cm_name : str The name of the element component. - omegax, omegay, omegaz - If the X2, Y2, Z2 fields are not defined, OMEGAX, OMEGAY, and - OMEGAZ specify the components of the rotational velocity vector in - the global Cartesian X, Y, Z directions. + omegax : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``OMEGAX``, ``OMEGAY``, and ``OMEGAZ`` + specify the components of the rotational velocity vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``OMEGAX`` is required. ``OMEGAX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``OMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + omegay : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``OMEGAX``, ``OMEGAY``, and ``OMEGAZ`` + specify the components of the rotational velocity vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``OMEGAX`` is required. ``OMEGAX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``OMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + omegaz : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``OMEGAX``, ``OMEGAY``, and ``OMEGAZ`` + specify the components of the rotational velocity vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``OMEGAX`` is required. ``OMEGAX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``OMEGAX`` is designated either positive or negative, and is determined by the "right hand + rule." + + x1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + y1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + z1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + x2 : str + The coordinates of the end point of the rotational axis vector. - x1, y1, z1 - If the X2, Y2, Z2 fields are defined,X1, Y1, and Z1 define the - coordinates of the beginning point of the rotational axis vector. - Otherwise, X1, Y1, and Z1 are the coordinates of a point through - which the rotational axis passes. + y2 : str + The coordinates of the end point of the rotational axis vector. - x2, y2, z2 + z2 : str The coordinates of the end point of the rotational axis vector. Notes ----- - Specifies the rotational velocity components OMEGAX, OMEGAY, and OMEGAZ - of an element component CM_NAME about a user-defined rotational axis. - The rotational axis can be defined either as a vector passing through a - single point or a vector connecting two points. - You can define rotational velocity and rotational axis for these - analysis types: + .. _CMOMEGA_notes: + + Specifies the rotational velocity components ``OMEGAX``, ``OMEGAY``, and ``OMEGAZ`` of an element + component ``CM_NAME`` about a user-defined rotational axis. The rotational axis can be defined + either as a vector passing through a single point or a vector connecting two points. - Static (ANTYPE,STATIC) + You can define the rotational velocity and rotational axis for these analysis types: - Harmonic (ANTYPE,HARMIC) -- Full or modal superposition + * Static ( :ref:`antype`,STATIC) - Transient (ANTYPE,TRANS) -- Full or modal superposition + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`CMOMEGA_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`CMOMEGA_FN_VT_KRY` ], or mode-superposition [ :ref:`CMOMEGA_mode-sup_LVSCALE` ] - Substructuring (ANTYPE,SUBSTR) + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`CMOMEGA_mode-sup_LVSCALE` ] - Modal (ANTYPE,MODAL) + * Substructuring ( :ref:`antype`,SUBSTR) - Rotational velocities are combined with the element mass matrices to - form a body force load vector term. Units are radians/time. Related - commands are ACEL, CGLOC, CGLOC, CGOMGA, CMDOMEGA, DCGOMG, DOMEGA. + * Modal ( :ref:`antype`,MODAL) - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + .. _CMOMEGA_FN_VT_KRY: - You can use the CMOMEGA command in conjunction with either one of the - following two groups of commands, but not with both groups - simultaneously: + Loads for VT and Krylov methods are supported as long as they are not: - Components for which you want to specify rotational loading must - consist of elements only. The elements you use cannot be part of more - than one component, and elements that share nodes cannot exist in - different element components. You cannot apply the loading to an - assembly of element components. + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) - If you have applied the Coriolis effect (CORIOLIS) using a stationary - reference frame, the CMOMEGA command takes the gyroscopic damping - matrix into account for the elements listed under "Stationary Reference - Frame" in the notes section of the CORIOLIS command. ANSYS verifies - that the rotation vector axis is parallel to the axis of the element; - if not, the gyroscopic effect is not applied. If you issue a CMOMEGA - command when the Coriolis or gyroscopic effect is present, a - subsequently issued OMEGA command has no effect. + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). - The CMOMEGA command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for CMOMEGA_X, CMOMEGA_Y, and CMOMEGA_Z - input values (``*DIM``) for full transient and harmonic analyses. + .. _CMOMEGA_mode-sup_LVSCALE: - 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 MODE file, which you can - apply via the LVSCALE command. + 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. + + Rotational velocities are combined with the element mass matrices to form a body-force load vector + term. Units are radians/time. Related commands are :ref:`acel`, :ref:`cgloc`, :ref:`cgloc`, + :ref:`cgomga`, :ref:`cmdomega`, :ref:`dcgomg`, :ref:`domega`. + + See `Analysis Tools + `_ + + You can use the :ref:`cmomega` command in conjunction with either one of the following two groups of + commands, but not with both groups simultaneously: + + * GROUP ONE: :ref:`omega`, :ref:`domega`. + * GROUP TWO: :ref:`cgomga`, :ref:`dcgomg`, :ref:`cgloc`. + + Components for which you want to specify rotational loading must consist of elements only. The + elements you use cannot be part of more than one component, and elements that share nodes cannot + exist in different element components. You cannot apply the loading to an assembly of element + components. + + If you have applied the Coriolis effect ( :ref:`coriolis` ) using a `stationary + `_ + reference frame, the :ref:`cmomega` command takes the gyroscopic damping matrix into account for the + elements listed under "Stationary Reference Frame" in the notes section of the :ref:`coriolis` + command. Mechanical APDL verifies that the rotation vector axis is parallel to the axis of the + element; if + not, the gyroscopic effect is not applied. If you issue a :ref:`cmomega` command when the Coriolis + or gyroscopic effect is present, a subsequently issued :ref:`omega` command has no effect. + + The :ref:`cmomega` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``OMEGAX``, ``OMEGAY``, and ``OMEGAZ`` input values ( :ref:`dim` ) for modal, + full transient, and full harmonic analyses. In this case, if the end point is specified ( ``X2``, + ``Y2``, ``Z2`` ), the rotational velocity axis must be along the global X-, Y-, or Z-axis. + + The load interpolation setting ( :ref:`kbc` ) applies to the rotational velocity, in particular the + ``OMGSQRDKEY`` option for quadratic interpolation. """ command = f"CMOMEGA,{cm_name},{omegax},{omegay},{omegaz},{x1},{y1},{z1},{x2},{y2},{z2}" return self.run(command, **kwargs) def cmrotate( self, - cm_name="", - rotatx="", - rotaty="", - rotatz="", - x1="", - y1="", - z1="", - x2="", - y2="", - z2="", + cm_name: str = "", + rotatx: str = "", + rotaty: str = "", + rotatz: str = "", + x1: str = "", + y1: str = "", + z1: str = "", + x2: str = "", + y2: str = "", + z2: str = "", **kwargs, ): - """Specifies the rotational velocity of an element component in a brake + r"""Specifies the rotational velocity of an element component in a brake-squeal analysis. - APDL Command: CMROTATE - squeal analysis. + Mechanical APDL Command: `CMROTATE `_ Parameters ---------- - cm_name + cm_name : str The name of the element component. - rotatx, rotaty, rotatz - If the X2, Y2, Z2 fields are not defined, ROTATX, ROTATY, and - ROTATZ specify the components of the rotational angle vector in the - global Cartesian X, Y, Z directions. + rotatx : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``ROTATX``, ``ROTATY``, and ``ROTATZ`` + specify the components of the rotational angle vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``ROTATX`` is required. ``ROTATX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``ROTATX`` is designated either positive or negative, and is determined by the "right hand + rule." + + rotaty : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``ROTATX``, ``ROTATY``, and ``ROTATZ`` + specify the components of the rotational angle vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``ROTATX`` is required. ``ROTATX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``ROTATX`` is designated either positive or negative, and is determined by the "right hand + rule." + + rotatz : str + If the ``X2``, ``Y2``, ``Z2`` fields are not defined, ``ROTATX``, ``ROTATY``, and ``ROTATZ`` + specify the components of the rotational angle vector in the global Cartesian X, Y, Z + directions. + + If the ``X2``, ``Y2``, ``Z2`` fields are defined, only ``ROTATX`` is required. ``ROTATX`` + specifies the scalar rotational velocity about the rotational axis. The rotational direction of + ``ROTATX`` is designated either positive or negative, and is determined by the "right hand + rule." + + x1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + y1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + z1 : str + If the ``X2``, ``Y2``, ``Z2`` fields are defined, ``X1``, ``Y1``, and ``Z1`` define the + coordinates of the beginning point of the rotational axis vector. Otherwise, ``X1``, ``Y1``, and + ``Z1`` are the coordinates of a point through which the rotational axis passes. + + x2 : str + The coordinates of the end point of the rotational axis vector. - x1, y1, z1 - If the X2, Y2, Z2 fields are defined, X1, Y1, and Z1 define the - coordinates of the beginning point of the rotational axis vector. - Otherwise, X1, Y1, and Z1 are the coordinates of a point through - which the rotational axis passes. + y2 : str + The coordinates of the end point of the rotational axis vector. - x2, y2, z2 + z2 : str The coordinates of the end point of the rotational axis vector. Notes ----- - The CMROTATE command specifies the rotational motion velocity - components ROTATX, ROTATY, and ROTATZ of an element component CM_Name - about a user-defined rotational axis. The rotational axis can be - defined either as a vector passing through a single point or a vector - connecting two points. CMROTATE can be used in static analyses - (ANTYPE,STATIC) and modal analyses (ANTYPE,MODAL). - - This command sets the constant rotational velocity on the nodes of the - specified element component, despite any deformation at the nodes. This - feature is primarily used for generating sliding contact at frictional - contact interfaces in a brake squeal analysis. This type of analysis - typically involves surface-to-surface contact between the brake pad and - the rotating disk. The applicable contact elements, therefore, are - CONTA173, CONTA174, and CONTA175. - - A brake squeal analysis generally involves a linear perturbation modal - analysis subsequent to a large-deformation static analysis with the - Newton-Raphson option set as NROPT,UNSYM. Therefore, CMROTATE is not - applicable for multiple load step solves using the LSSOLVE command. + The :ref:`cmrotate` command specifies the rotational motion velocity components ``ROTATX``, + ``ROTATY``, and ``ROTATZ`` of an element component ``CM_Name`` about a user-defined rotational axis. + The rotational axis can be defined either as a vector passing through a single point or a vector + connecting two points. :ref:`cmrotate` can be used in static analyses ( :ref:`antype`,STATIC) and + modal analyses ( :ref:`antype`,MODAL). + + This command sets the constant rotational velocity on the nodes of the specified element component, + despite any deformation at the nodes. This feature is primarily used for generating sliding contact + at frictional contact interfaces in a `brake-squeal analysis + `_. + This type of analysis typically involves surface-to-surface contact between the brake pad and the + rotating disk. The applicable contact elements, therefore, are ``CONTA174`` and ``CONTA175``. + + A `brake-squeal analysis + `_ + generally involves a linear perturbation modal analysis subsequent to a large-deformation static + analysis with the Newton-Raphson option set as :ref:`nropt`,UNSYM. Therefore, :ref:`cmrotate` is not + applicable for multiple load step solves using the :ref:`lssolve` command. + + The load interpolation setting ( :ref:`kbc` ) applies to the rotational velocity, in particular the + ``OMGSQRDKEY`` option for quadratic interpolation. This command is also valid in PREP7. """ command = f"CMROTATE,{cm_name},{rotatx},{rotaty},{rotatz},{x1},{y1},{z1},{x2},{y2},{z2}" return self.run(command, **kwargs) - def coriolis(self, option="", refframe="", rotdamp="", rotmass="", **kwargs): - """Applies the Coriolis effect to a rotating structure. + def coriolis( + self, + option: str = "", + refframe: str = "", + rotdamp: str = "", + rotmass: str = "", + **kwargs, + ): + r"""Applies the Coriolis effect to a rotating structure. - APDL Command: CORIOLIS + Mechanical APDL Command: `CORIOLIS `_ Parameters ---------- @@ -506,77 +844,79 @@ def coriolis(self, option="", refframe="", rotdamp="", rotmass="", **kwargs): ``"OFF"``, ``"NO"``, or ``False`` - Deactivate. This value is the default. rotmass : str, bool, optional - Flag to activate or deactivate rotor mass summary printout - (only supported for ``refframe='on'``). + Flag to activate or deactivate rotor mass summary printout + (only supported for ``refframe='on'``). - ``"ON"``, ``"YES"``, or ``True`` - Activate. + ``"ON"``, ``"YES"``, or ``True`` - Activate. - ``"OFF"``, ``"NO"``, or ``False`` - Deactivate. This value is the default. + ``"OFF"``, ``"NO"``, or ``False`` - Deactivate. This value is the default. Notes ----- - The CORIOLIS command is used for analyses in either a rotating - or a stationary reference frame, and performs differently - according to the designated RefFrame value. Specific - restrictions and elements apply to each case, as follows: - - ROTATING REFERENCE FRAME ``refframe=False``): - - The command applies the Coriolis effect in the following - structural element types: MASS21, SHELL181, PLANE182, - PLANE183, SOLID185, SOLID186, SOLID187, BEAM188, BEAM189, - SOLSH190, SHELL281, PIPE288 and PIPE289. It also applies this - effect in the PLANE223, SOLID226, and SOLID227 analyses with - structural degrees of freedom. - - In a rotating reference frame, both the Coriolis and - spin-softening effects contribute to the gyroscopic - moment. Therefore, ANSYS applies spin-softening by default for - dynamic analyses. If a rotational velocity is specified (OMEGA - or CMOMEGA), centrifugal forces will be included. - - To include Coriolis effects in a large deflection prestressed - analysis, follow the procedure for linear perturbation - detailed in Considerations for Rotating Structures. In a - nonlinear transient analysis (ANTYPE,TRANS and NLGEOM, ON), - any spinning motion applied through either the IC of the D - commands will include the Coriolis effect without having to - issue the CORIOLIS command. Refer to Rotating Structure - Analysis in the Advanced Analysis Guide for more information. - - STATIONARY REFERENCE FRAME ``refframe=True``): - - The command activates the gyroscopic damping matrix in the - following structural elements: MASS21, BEAM188, SHELL181, - BEAM189, SOLID185, SOLID186, SOLID187, SOLID272, SOLID273, - SHELL281, PIPE288, PIPE289, and MATRIX50. - - The rotating structure must be axisymmetric about the axis of - rotation. - - Static analysis (ANTYPE, STATIC) does not support Coriolis - effects with a stationary reference frame. However, you can - include the gyroscopic effects in a prestresses analysis - follow the procedure detailed in Considerations for Rotating - Structures. - - Rotating damping effect (RotDamp = ON) applies only for the - stationary reference frame. Therefore, this effect is - supported only by the elements listed above that generate a - gyroscopic damping matrix. Proportional damping must be - present in the element (MP,BETD or BETAD). It is also - supported by element COMBI214 with non zero and axisymmetric - damping characteristics (non zero real constants C11=C22 and - C21=C12=0). - - For more information about using the CORIOLIS command, see - Rotating Structure Analysis in the Advanced Analysis Guide and - also in the Rotordynamic Analysis Guide. For details about the - Coriolis and gyroscopic effect element formulations, see the - Mechanical APDL Theory Reference. - - Elements with layered section properties do not support - Coriolis effects (rotating and stationary reference frames). + The :ref:`coriolis` command is used for linear analyses in either a rotating or a stationary + reference frame, and performs differently according to the designated ``RefFrame`` value. The + :ref:`coriolis` command must be specified during the first step of the analysis. The rotational + velocity must be defined using :ref:`omega` (when the whole model is rotating) or :ref:`cmomega` + (component based rotation). Specific restrictions and elements apply to each case, as follows: + + * `Rotating Reference Frame + `_ (, RefFrame + = OFF) - The command applies the Coriolis effect in the following structural element types: + ``MASS21``, ``SHELL181``, ``PLANE182``, ``PLANE183``, ``SOLID185``, ``SOLID186``, ``SOLID187``, + ``BEAM188``, ``BEAM189``, ``SOLSH190``, ``SHELL281``, ``PIPE288`` and ``PIPE289``. It also applies + this effect in the following coupled-field elements when structural degrees of freedom are present: + ``PLANE222``, ``PLANE223``, ``SOLID225``, ``SOLID226``, and ``SOLID227``. + + The rotating damping effect ( ``RotDamp`` = ON) is only supported by the ``COMBI214`` element when + stationary. + + In a rotating reference frame, the Coriolis and `spin-softening + `_ effects, as + well as the centrifugal forces, contribute to the dynamics and are applied by default. + + * `Stationary Reference Frame + `_ + (, RefFrame = ON) - The command activates the gyroscopic damping matrix in the following structural + elements: ``MASS21``, ``BEAM188``, ``SHELL181``, ``BEAM189``, ``SOLID185``, ``SOLID186``, + ``SOLID187``, ``SOLSH190``, ``SOLID272``, ``SOLID273``, ``SHELL281``, ``PIPE288``, ``PIPE289``, and + ``MATRIX50``. + + The rotating structure is assumed to be axisymmetric about the axis of rotation. + + The rotating damping effect ( ``RotDamp`` = ON) is supported by the elements listed above that + generate a gyroscopic damping matrix. It is also supported by some specific elements (see for a + complete list). + + The rotor mass summary printout ( ``RotMass`` = ON) is only supported for some of the elements that + generate a gyroscopic damping matrix: ``MASS21``, ``BEAM188``, ``BEAM189``, ``PIPE288``, and + ``PIPE289``. The EMAT file is required ( :ref:`ematwrite`,YES). + + To include Coriolis effects in a linear perturbation (prestressed) analysis, follow the procedure + detailed in `Considerations for Rotating Structures + `_ + + In a nonlinear transient analysis in which the model is actually spinning ( :ref:`antype`,TRANS and + :ref:`nlgeom`,ON) the :ref:`coriolis` command must not be used as any spinning motion applied + through either the :ref:`ic` or :ref:`d` commands automatically includes nonlinear inertia terms + such as the Coriolis effect. + + To take into account variable bearings ( ``COMBI214`` elements with tabular user-defined + characteristics), you must activate the Coriolis effect in a stationary reference frame. The + gyroscopic effect coming from ``COMBI214`` mass characteristics is not supported. + + For more information about using the :ref:`coriolis` command, see `Rotating Structure Analysis + `_ in the + `Advanced Analysis Guide + `_ and also in + the `Rotordynamic Analysis Guide + `_. For details + about the Coriolis and gyroscopic effect element + formulations, see the `Mechanical APDL Theory Reference + `_. + + Elements with `layered section properties + `_ + do not support Coriolis effects (rotating and stationary reference frames). This command is also valid in PREP7. @@ -590,256 +930,405 @@ def coriolis(self, option="", refframe="", rotdamp="", rotmass="", **kwargs): >>> mapdl.coriolis(True, refframe=True) """ - # handle bool instead of strings if isinstance(option, bool): option = int(option) - if isinstance(refframe, bool): refframe = int(refframe) - if isinstance(rotdamp, bool): rotdamp = int(rotdamp) - if isinstance(rotmass, bool): rotmass = int(rotdamp) - command = f"CORIOLIS,{option},,,{refframe},{rotdamp},{rotmass}" return self.run(command, **kwargs) - def dcgomg(self, dcgox="", dcgoy="", dcgoz="", **kwargs): - """Specifies the rotational acceleration of the global origin. + def dcgomg(self, dcgox: str = "", dcgoy: str = "", dcgoz: str = "", **kwargs): + r"""Specifies the rotational acceleration of the global origin. - APDL Command: DCGOMG + Mechanical APDL Command: `DCGOMG `_ Parameters ---------- - dcgox, dcgoy, dcgoz - Rotational acceleration of the global origin about the acceleration - system X, Y, and Z axes. + dcgox : str + Rotational acceleration of the global origin about the acceleration system X, Y, and Z axes. + + dcgoy : str + Rotational acceleration of the global origin about the acceleration system X, Y, and Z axes. + + dcgoz : str + Rotational acceleration of the global origin about the acceleration system X, Y, and Z axes. Notes ----- - Specifies the rotational acceleration of the global origin about each - of the acceleration coordinate system axes [CGLOC]. Rotational - accelerations may be defined in analysis types ANTYPE,STATIC, HARMIC - (full or mode-superposition), TRANS (full or mode-superposition), and - SUBSTR. See Acceleration Effect in the Mechanical APDL Theory Reference - for details. Units are radians/time2. - The DCGOMG command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for DCGOMG_X, DCGOMG_Y, and DCGOMG_Z - input values (``*DIM``) for full transient and harmonic analyses. + .. _DCGOMG_notes: + + Specifies the rotational acceleration of the global origin about each of the acceleration coordinate + system axes ( :ref:`cgloc` ). Rotational accelerations may be defined in these analysis types: + + * Static ( :ref:`antype`,STATIC) + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`DCGOMG_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`DCGOMG_FN_VT_KRY` ], or mode-superposition [ :ref:`DCGOMG_mode-sup_LoadSupport` ] + + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`DCGOMG_mode-sup_LoadSupport` ] + + * Substructuring ( :ref:`antype`,SUBSTR) + + * Modal ( :ref:`antype`,MODAL) + + .. _DCGOMG_FN_VT_KRY: + + Loads for VT and Krylov methods are supported as long as they are not: + + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) + + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). + + .. _DCGOMG_mode-sup_LoadSupport: - Related commands are ACEL, CGLOC, CGOMGA, DOMEGA, and OMEGA. + 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. - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + See `Acceleration Effect + `_ :sup:`2`. + + The :ref:`dcgomg` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``DCGOMG_X``, ``DCGOMG_Y``, and ``DCGOMG_Z`` input values ( :ref:`dim` ) for full + transient and harmonic analyses. + + Related commands are :ref:`acel`, :ref:`cgloc`, :ref:`cgomga`, :ref:`domega`, and :ref:`omega`. + + See `Analysis Tools + `_ This command is also valid in PREP7. """ command = f"DCGOMG,{dcgox},{dcgoy},{dcgoz}" return self.run(command, **kwargs) - def domega(self, domgx="", domgy="", domgz="", **kwargs): - """Specifies the rotational acceleration of the structure. + def domega(self, domgx: str = "", domgy: str = "", domgz: str = "", **kwargs): + r"""Specifies the rotational acceleration of the structure. - APDL Command: DOMEGA + Mechanical APDL Command: `DOMEGA `_ Parameters ---------- - domgx, domgy, domgz - Rotational acceleration of the structure about the global Cartesian - X , Y, and Z axes. + domgx : str + Rotational acceleration of the structure about the global Cartesian X, Y, and Z axes. + + domgy : str + Rotational acceleration of the structure about the global Cartesian X, Y, and Z axes. + + domgz : str + Rotational acceleration of the structure about the global Cartesian X, Y, and Z axes. Notes ----- - Specifies the rotational acceleration of the structure about each of - the global Cartesian axes. Rotational accelerations may be defined in - analysis types ANTYPE,STATIC, HARMIC (full or mode-superposition), - TRANS (full or mode-superposition), and SUBSTR. See Acceleration - Effect in the Mechanical APDL Theory Reference for details. Units are - radians/time2. - The DOMEGA command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for DOMEGA_X, DOMEGA_Y, and DOMEGA_Z - input values (``*DIM``) for full transient and harmonic analyses. + .. _DOMEGA_notes: + + Specifies the rotational acceleration of the structure about each of the global Cartesian axes. + Rotational accelerations may be defined in these analysis types: + + * Static ( :ref:`antype`,STATIC) + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`DOMEGA_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`DOMEGA_FN_VT_KRY` ], or mode-superposition [ :ref:`DOMEGA_mode-sup_LoadSupport` ] + + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`DOMEGA_mode-sup_LoadSupport` ] + + * Substructuring ( :ref:`antype`,SUBSTR) - Related commands are ACEL, CGLOC, CGOMGA, DCGOMG, and OMEGA. + * Modal ( :ref:`antype`,MODAL) - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + .. _DOMEGA_FN_VT_KRY: - In a modal 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 mode shape file, which you can apply via - the LVSCALE command. + Loads for VT and Krylov methods are supported as long as they are not: + + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) + + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). + + .. _DOMEGA_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. + + See `Acceleration Effect + `_ :sup:`2`. + + The :ref:`domega` command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and + ``TABNAME_Z``) for ``DOMEGA_X``, ``DOMEGA_Y``, and ``DOMEGA_Z`` input values ( :ref:`dim` ) for full + transient and harmonic analyses. + + Related commands are :ref:`acel`, :ref:`cgloc`, :ref:`cgomga`, :ref:`dcgomg`, and :ref:`omega`. + + See `Analysis Tools + `_ This command is also valid in PREP7. """ command = f"DOMEGA,{domgx},{domgy},{domgz}" return self.run(command, **kwargs) - def irlf(self, key="", **kwargs): - """Specifies that inertia relief calculations are to be performed. + def irlf( + self, + key: int | str = "", + printfreq: int | str = "", + rampkey: int | str = "", + **kwargs, + ): + r"""Specifies that inertia relief calculations are to be performed. - APDL Command: IRLF + Mechanical APDL Command: `IRLF `_ Parameters ---------- - key + key : int or str Calculation key: - 0 - No inertia relief calculations. + * ``0`` - No inertia relief calculations. + + * ``1`` - Counterbalance loads with inertia relief forces. + + * ``-1`` - Precalculate masses for summary printout only (no inertia relief). + + printfreq : int or str + Frequency at which inertia relief information is printed during substeps in a nonlinear static or + eigenvalue buckling analysis. This value must be a positive integer, 0, or ALL, as described below. + + * ``0`` - No inertia relief information is printed during the Newton Raphson substeps (default). + + * ``n`` - Prints inertia relief information every ``n`` th substep of each load step. - 1 - Counterbalance loads with inertia relief forces. + * ``ALL`` - Prints inertia relief information every substep. - -1 - Precalculate masses for summary printout only (no inertia relief). + rampkey : int or str + Key to control ramping of rigid body accelerations. See notes for steps to achieve convergence when :ref:`turning on the inertia relief option in the second or later load step of a nonlinear analysis. ` + + * ``0`` - (Default) Rigid body acceleration is stepped and ramped together with total external loads + following specifications set using the :ref:`kbc` command. Normally, the inertia relief option is + turned on at the first load step. + + * ``1`` - Ramp the rigid body accelerations alone following specifications set by the :ref:`kbc` + command. This option is only used for better convergence when the inertia relief load step is + nonlinear and the inertia relief option is turned on from a later load step (other than the first). + It works with :ref:`kbc`,0 specified and no new loads added to the current load step. After the + current load step, ``RampKey`` is automatically set to 0. See :ref:`IRLF_Note_LateLoadStep`. Notes ----- - The IRLF command specifies that the program is to calculate - accelerations to counterbalance the applied loads (inertia relief). - Displacement constraints on the structure should be only those - necessary to prevent rigid-body motions (3 are needed for a 2-D - structure and 6 for a 3-D structure). The sum of the reaction forces - at the constraint points will be zero. Accelerations are calculated - from the element mass matrices and the applied forces. Data needed to - calculate the mass (such as density) must be input. Both translational - and rotational accelerations may be calculated. - - This option applies only to the static (ANTYPE,STATIC) analysis. - Nonlinearities, elements that operate in the nodal coordinate system, - and axisymmetric or generalized plane strain elements are not allowed. - Symmetry models are not valid for inertia relief analysis. Models with - both 2-D and 3-D element types are not recommended. - - Loads may be input as usual. Displacements and stresses are calculated - as usual. - - Use IRLIST to print inertia relief calculation results. The mass and - moment of inertia summary printed before the solution is accurate - (because of the additional pre-calculations required for inertia - relief). See Inertia Relief in the Mechanical APDL Theory Reference - for calculation details. See also the Structural Analysis Guide for - procedural details. - - If the inertia relief calculation is to be performed in the second or - later load step, you must specify EMATWRITE,YES in the initial load - step for the element matrices needed to perform the calculations to be - available. - - When a superelement (MATRIX50) is present in the model, any DOF - constraints that you need to apply (D) on a degree of freedom (DOF) - belonging to the superelement must be applied in the use pass of the - MATRIX50 element (not in the generation pass). The command has no - effect in the generation pass of a substructure. In the expansion pass, - precalculation of masses for summary printout (IRLF,-1) occurs only on - elements that are part of the substructure. + + .. _IRLF_notes: + + The :ref:`irlf` command specifies that the program is to calculate accelerations to counterbalance + the applied loads (inertia relief). Displacement constraints on the structure should be only those + necessary to prevent rigid-body motions (3 are needed for a 2D structure and 6 for a 3D structure). + If the minimum number of displacement constraints are applied and it is a linear static analysis, + the sum of the reaction forces at the constrained points will be zero. However, if it is a nonlinear + static analysis ( :ref:`nlgeom`,ON), the sum of reaction forces at the constrained points will be + approximately zero due to the error introduced by nonlinear iterations. Accelerations are calculated + from the element mass matrices and the applied forces. Data needed to calculate the mass (such as + density) must be input. Both translational and rotational accelerations may be calculated. + + This option applies to the following analyses: static (linear or nonlinear), linear perturbation + static, and buckling (see `Including Inertia Relief Calculations + `_ `Supported + Analysis Types for Inertia Relief + `_ Elements that + operate in the nodal coordinate system and axisymmetric or generalized plane strain elements are not + allowed. Symmetry models are not valid for inertia relief analysis. Models with both 2D and 3D + element types are not recommended. + + Loads may be input as usual. Displacements and stresses are calculated as usual. + + An automatic inertia relief capability is available for linear static analysis only. See the + :ref:`airl` command for details. + + Use :ref:`irlist` to print inertia relief calculation results. Note that :ref:`irlist` can only be + issued at the end of the analysis, right after the :ref:`solve` command in the nonlinear case. To + print information during substeps in a nonlinear static or eigenvalue buckling analysis, set + ``PrintFreq`` as described above. The mass and moment of inertia summary printed before the solution + is accurate (because of the additional pre-calculations required for inertia relief). See `Inertia + Relief + `_ + + Turning On the Inertia Relief Option in the Second or Later Load Step If the inertia relief option + is turned on in the second or later load step in a nonlinear static + analysis, follow these precautionary steps for easy nonlinear convergence: + + At the second or higher load step, where :ref:`irlf`,1 is issued the first time, do not apply new + external loads. + + Set ``Rampkey`` = 1 at this load step and :ref:`kbc`,0 so that the rigid body accelerations are + ramped. + + Use the :ref:`nsubst` or :ref:`deltim` command to allow more substeps in this load step. + + When a superelement ( ``MATRIX50`` ) is present in the model, any DOF constraints that you need to + apply ( :ref:`d` ) on a degree of freedom (DOF) belonging to the superelement must be applied in the + `use pass + `_ + of the ``MATRIX50`` element ( not in the `generation pass + `_ + ). The command has no effect in the `generation pass + `_ + of a substructure. In the `expansion pass + `_, + precalculation of masses for summary printout ( :ref:`irlf`,-1) occurs only on elements that are + part of the substructure. This command is also valid in PREP7. + + **Example Usage** + Example command inputs for including inertia relief calculations in a static analysis with geometric + nonlinearity, a linear perturbation static analysis, and a linear perturbation buckling analysis are + found in `Including Inertia Relief Calculations + `_ """ - command = f"IRLF,{key}" + command = f"IRLF,{key},{printfreq},{rampkey}" return self.run(command, **kwargs) - def omega(self, omegx="", omegy="", omegz="", **kwargs): - """Specifies the rotational velocity of the structure. + def omega(self, omegx: str = "", omegy: str = "", omegz: str = "", **kwargs): + r"""Specifies the rotational velocity of the structure. - APDL Command: OMEGA + Mechanical APDL Command: `OMEGA `_ Parameters ---------- - omegx, omegy, omegz - Rotational velocity of the structure about the global Cartesian X, - Y, and Z axes. + omegx : str + Rotational velocity of the structure about the global Cartesian X, Y, and Z axes. + + omegy : str + Rotational velocity of the structure about the global Cartesian X, Y, and Z axes. + + omegz : str + Rotational velocity of the structure about the global Cartesian X, Y, and Z axes. Notes ----- - This command specifies the rotational velocity of the structure about - each of the global Cartesian axes (right-hand rule). Rotational - velocities may be defined in these analysis types: - Static (ANTYPE,STATIC) + .. _OMEGA_notes: + + This command specifies the rotational velocity of the structure about each of the global Cartesian + axes (right-hand rule). Rotational velocities may be defined in these analysis types: + + * Static ( :ref:`antype`,STATIC) + + * Harmonic ( :ref:`antype`,HARMIC) -- full, `VT + `_ [ + :ref:`OMEGA_FN_VT_KRY` ], `Krylov + `_ + [ :ref:`OMEGA_FN_VT_KRY` ], or mode-superposition [ :ref:`OMEGA_mode-sup_LoadSupport` ] + + * Transient ( :ref:`antype`,TRANS) -- `full + `_ + or mode-superposition [ :ref:`OMEGA_mode-sup_LoadSupport` ] - Harmonic (ANTYPE,HARMIC) -- Full or mode-superposition + * Substructuring ( :ref:`antype`,SUBSTR) - Transient (ANTYPE,TRANS) -- Full or mode-superposition + * Modal ( :ref:`antype`,MODAL) - Substructuring (ANTYPE,SUBSTR) + .. _OMEGA_FN_VT_KRY: - Modal (ANTYPE,MODAL) + Loads for VT and Krylov methods are supported as long as they are not: - The OMEGA command supports tabular boundary conditions (%TABNAME_X%, - %TABNAME_Y%, and %TABNAME_Z%) for OMEGA_X, OMEGA_Y, and OMEGA_Z input - values (``*DIM``) for full transient and harmonic analyses. + * complex tabulated loads (constant or trapezoidal loads in tabulated form are supported) - Rotational velocities are combined with the element mass matrices to - form a body force load vector term. Units are radians/time. Related - commands are ACEL, CGLOC, CGOMGA, DCGOMG, and DOMEGA. + * used in conjunction with Rotordynamics ( :ref:`coriolis`,on). - See Analysis Tools in the Mechanical APDL Theory Reference for more - information. + .. _OMEGA_mode-sup_LoadSupport: - If you have applied the Coriolis effect (CORIOLIS) using a stationary - reference frame, the OMEGA command takes the gyroscopic damping matrix - into account for the elements listed in the "Stationary Reference - Frame" heading in the notes section of the CORIOLIS command. The - element axis must pass through the global Cartesian origin. ANSYS - verifies that the rotation vector axis is parallel to the axis of the - element; if not, the gyroscopic effect is not applied. After issuing - the OMEGA command when the Coriolis or gyroscopic effect is present, a - subsequently issued CMOMEGA command has no effect. + 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. - 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 MODE file, which you can - apply via the LVSCALE command. + The command supports tabular boundary conditions (``TABNAME_X``, ``TABNAME_Y``, and ``TABNAME_Z``) + for ``OMEGA_X``, ``OMEGA_Y``, and ``OMEGA_Z`` input values ( :ref:`dim` ) for full transient and + harmonic analyses. + + Rotational velocities are combined with the element mass matrices to form a body-force load vector + term. Units are radians/time. Related commands are :ref:`acel`, :ref:`cgloc`, :ref:`cgomga`, + :ref:`dcgomg`, and :ref:`domega`. + + See `Analysis Tools + `_ + + If you have applied the Coriolis effect ( :ref:`coriolis` ) using a `stationary reference frame + `_, + this command takes the gyroscopic damping matrix into account for the elements listed in the + **Stationary Reference Frame** heading in the notes section of the :ref:`coriolis` command. The + element axis must pass through the global Cartesian origin. The program verifies that the rotation + vector axis is parallel to the axis of the element; if not, the gyroscopic effect is not applied. + After issuing :ref:`omega` when the Coriolis or gyroscopic effect is present, a subsequently issued + :ref:`cmomega` command has no effect. + + The load interpolation setting ( :ref:`kbc` ) applies to the rotational velocity, in particular the + ``OMGSQRDKEY`` option for quadratic interpolation. This command is also valid in PREP7. """ command = f"OMEGA,{omegx},{omegy},{omegz}" return self.run(command, **kwargs) - def synchro(self, ratio="", cname="", **kwargs): - """Specifies whether the excitation frequency is synchronous or + def synchro(self, ratio: str = "", cname: str = "", **kwargs): + r"""Specifies whether the excitation frequency is synchronous or asynchronous with the rotational + velocity of a structure. - APDL Command: SYNCHRO - asynchronous with the rotational velocity of a structure. + Mechanical APDL Command: `SYNCHRO `_ Parameters ---------- - ratio - The ratio between the frequency of excitation and the frequency of - the rotational velocity of the structure. This value must be - greater than 0. The default is an unbalance excitation (RATIO = - 1.0). + ratio : str + In a stationary reference frame ( :ref:`coriolis` with ``RefFrame`` = ON), ``RATIO`` is the + ratio between the frequency of excitation and the frequency of the rotational velocity of the + structure. This value must be greater than 0. The default is an unbalance excitation. + + In a rotating reference frame ( :ref:`coriolis` with ``RefFrame`` = OFF), ``RATIO`` is the ratio + between the frequency of excitation and the frequency of the rotational velocity of the + structure minus 1. This value must be greater than 0. There is no default. - cname - The name of the rotating component on which to apply the harmonic - excitation. + cname : str + The name of the rotating component on which to apply the harmonic excitation. Notes ----- - The SYNCHRO command specifies whether the excitation frequency is - synchronous or asynchronous with the rotational velocity of a structure - in a harmonic analysis. Use the command to take into account rotating - harmonic forces on rotating structures. - - Mechanical APDL calculatestes the rotational velocity Ω of the - structure from the excitation frequency f, defined (via the HARFRQ - command) as Ω = 2πf / RATIO. The rotational velocity is applied along - the direction cosines of the rotation axis (specified via an OMEGA or - CMOMEGA command). - - Specifying any value for RATIO causes a general rotational force - excitation and not an unbalance force. To define an unbalance - excitation force (F = Ω2 * Unb), RATIO should be left blank (the nodal - unbalance Unb is specified via the F command). - - The SYNCHRO command is valid only for a full-solution harmonic analysis - (HROPT,Method = FULL) and the Variational Technology method - (HROPT,Method = VT) involving a rotating structure (OMEGA or CMOMEGA) - with Coriolis enabled in a stationary reference frame - (CORIOLIS,,,,RefFrame = ON). + The :ref:`synchro` command specifies whether the excitation frequency is synchronous or asynchronous + with the rotational velocity of a structure in a harmonic analysis. Use the command to take into + account rotating harmonic forces on rotating structures. + + Mechanical APDL calculates the rotational velocity Ω of the structure from the excitation frequency + f, + defined (via the :ref:`harfrq` command) as Ω = 2π f / ``RATIO``. The rotational velocity is applied + along the direction cosines of the rotation axis (specified via an :ref:`omega` or :ref:`cmomega` + command). + + In a stationary reference frame, specifying any value for ``RATIO`` causes a general rotational + force excitation and not an unbalance force. To define an unbalance excitation force (F = Ω :sup:`2` + * Unb), ``RATIO`` should be left blank (the nodal unbalance Unb is specified via the :ref:`f` + command). + + In a rotating reference frame ( :ref:`coriolis` with ``RefFrame`` = OFF), an unbalance excitation is + a static load; therefore, a value must be supplied for ``RATIO``. + + The :ref:`synchro` command is valid only for the full harmonic analysis method ( :ref:`hropt`,FULL) + and the frequency-sweep harmonic analysis method ( :ref:`hropt`,VT) involving a rotating structure ( + :ref:`omega` or :ref:`cmomega` ) with Coriolis enabled ( :ref:`coriolis` ). """ command = f"SYNCHRO,{ratio},{cname}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/load_step_operations.py b/src/ansys/mapdl/core/_commands/solution/load_step_operations.py index c3420f611c1..ae4c68b371b 100644 --- a/src/ansys/mapdl/core/_commands/solution/load_step_operations.py +++ b/src/ansys/mapdl/core/_commands/solution/load_step_operations.py @@ -22,234 +22,213 @@ class LoadStepOperations: - def lsclear(self, lab="", **kwargs): - """Clears loads and load step options from the database. - APDL Command: LSCLEAR + def lsclear(self, lab: str = "", **kwargs): + r"""Clears loads and load step options from the database. + + Mechanical APDL Command: `LSCLEAR `_ Parameters ---------- - lab + lab : str Label identifying the data to be cleared: - SOLID - Delete only solid model loads. + * ``SOLID`` - Delete only solid model loads. - FE - Delete only finite element loads. + * ``FE`` - Delete only finite element loads. - INER - Delete only inertia loads (ACEL, etc.). + * ``INER`` - Delete only inertia loads ( :ref:`acel`, etc.). - LFACT - Initialize only load factors (on DCUM, FCUM, SFCUM, etc.). + * ``LFACT`` - Initialize only load factors (on :ref:`dcum`, :ref:`fcum`, :ref:`sfcum`, etc.). - LSOPT - Initialize only load step options. + * ``LSOPT`` - Initialize only load step options. - ALL - Delete all loads and initialize all load step options and load factors. + * ``ALL`` - Delete all loads and initialize all load step options and load factors. Notes ----- - Loads are deleted, and load step options are initialized to their - default values. + + .. _LSCLEAR_notes: + + Loads are deleted, and load step options are initialized to their default values. This command is also valid in PREP7. """ command = f"LSCLEAR,{lab}" return self.run(command, **kwargs) - def lsdele(self, lsmin="", lsmax="", lsinc="", **kwargs): - """Deletes load step files. + def lsdele(self, lsmin: str = "", lsmax: str = "", lsinc: str = "", **kwargs): + r"""Deletes load step files. - APDL Command: LSDELE + Mechanical APDL Command: `LSDELE `_ Parameters ---------- - lsmin, lsmax, lsinc - Range of load step files to be deleted, from LSMIN to LSMAX in - steps of LSINC. LSMAX defaults to LSMIN, and LSINC defaults to 1. - If LSMIN = ALL, all load step files are deleted (and LSMAX and - LSINC are ignored). The load step files are assumed to be named - Jobname.Sn, where n is a number assigned by the LSWRITE command (01 - --09,10,11, etc.). On systems with a 3-character limit on the - extension, the "S" is dropped for numbers > 99. + lsmin : str + Range of load step files to be deleted, from ``LSMIN`` to ``LSMAX`` in steps of ``LSINC``. + ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` = ALL, all load step + files are deleted (and ``LSMAX`` and ``LSINC`` are ignored). The load step files are assumed to + be named :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01 + --09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. + + lsmax : str + Range of load step files to be deleted, from ``LSMIN`` to ``LSMAX`` in steps of ``LSINC``. + ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` = ALL, all load step + files are deleted (and ``LSMAX`` and ``LSINC`` are ignored). The load step files are assumed to + be named :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01 + --09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. + + lsinc : str + Range of load step files to be deleted, from ``LSMIN`` to ``LSMAX`` in steps of ``LSINC``. + ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` = ALL, all load step + files are deleted (and ``LSMAX`` and ``LSINC`` are ignored). The load step files are assumed to + be named :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01 + --09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. Notes ----- - Deletes load step files in the current directory (written by the - LSWRITE command). + + .. _LSDELE_notes: + + Deletes load step files in the current directory (written by the :ref:`lswrite` command). This command is also valid in PREP7. """ command = f"LSDELE,{lsmin},{lsmax},{lsinc}" return self.run(command, **kwargs) - def lsread(self, lsnum="", **kwargs): - """Reads load and load step option data into the database. + def lsread(self, lsnum: str = "", **kwargs): + r"""Reads load and load step option data into the database. - .. warning:: This command can only run in non-interactive mode. - Please visit `Unsupported "Interactive" Commands - `_ - for further information. + Mechanical APDL Command: `LSREAD `_ - APDL Command: LSREAD + .. warning:: + + This command must be run using :func:`non_interactive `. + Please visit `Unsupported Interactive Commands `_ + for further information. Parameters ---------- - lsnum - Identification number of the load step file to be read. Defaults - to 1 + highest number read in the current session. Issue - LSREAD,STAT to list the current value of LSNUM. Issue LSREAD,INIT - to reset LSNUM to 1. The load step files are assumed to be named - Jobname.Sn, where n is a number assigned by the LSWRITE command (01 - --09,10,11, etc.). On systems with a 3-character limit on the - extension, the "S" is dropped for LSNUM > 99. + lsnum : str + Identification number of the load step file to be read. Defaults to 1 + highest number read in + the current session. Issue :ref:`lsread`,STAT to list the current value of ``LSNUM``. Issue + :ref:`lsread`,INIT to reset ``LSNUM`` to 1. The load step files are assumed to be named + :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01-- + 09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + ``LSNUM`` > 99. Notes ----- - Reads load and load step option data from the load step file into the - database. LSREAD will not clear the database of all current loads. - However, if a load is respecified with LSREAD, then it will overwrite - the existing load. See the LSWRITE command to write load step files, - and the LSDELE command to delete load step files. LSREAD removes any - existing SFGRAD specification. - - This command is also valid in PREP7. - - Examples - -------- - Demonstrate writing out load steps using :func:`lswrite - and reading them back in using - ``lsread``. - - >>> from ansys.mapdl.core import launch_mapdl - >>> mapdl = launch_mapdl() - >>> mapdl.clear() - >>> mapdl.prep7() - - Build a 5 x 5 flat plate out of shell181 elements. - - >>> mapdl.rectng(0, 5, 0, 5) - >>> mapdl.et(1, 'SHELL181') - >>> mapdl.mp('ex', 1, 10.0e5) - >>> mapdl.sectype(1, 'shell') - >>> mapdl.secdata(0.1) # 0.1 thick - >>> mapdl.esize(1) - >>> mapdl.amesh('all') - - Fix the four corners - >>> mapdl.d('node(0,0,0)', 'all') - >>> mapdl.d('node(0,5,0)', 'all') - >>> mapdl.d('node(5,5,0)', 'all') - >>> mapdl.d('node(5,0,0)', 'all') + .. _LSREAD_notes: - Enter the solution routine and define a force at (2,2,0). + Reads load and load step option data from the load step file into the database. :ref:`lsread` will + not clear the database of all current loads. However, if a load is respecified with :ref:`lsread`, + then it will overwrite the existing load. See the :ref:`lswrite` command to write load step files, + and the :ref:`lsdele` command to delete load step files. :ref:`lsread` removes any existing + :ref:`sfgrad` specification. - >>> mapdl.slashsolu() - >>> mapdl.antype('static') - >>> mapdl.f('node(2,2,0)', 'fz', -10) - - Write load out as load step 1 and delete all loads and displacements. - - >>> mapdl.lswrite(1) - >>> mapdl.fdele('all', 'all') - >>> mapdl.ddele('all', 'all') - - Read back in the loads and list them. - - >>> mapdl.lsread(1) - >>> mapdl.flist() - LIST NODAL FORCES FOR SELECTED NODES 1 TO 36 BY 1 - CURRENTLY SELECTED NODAL LOAD SET= FX FY FZ MX MY MZ - - *** MAPDL - ENGINEERING ANALYSIS SYSTEM RELEASE 2022 R2 22.2 *** - Ansys Mechanical Enterprise - 00000000 VERSION=LINUX x64 10:15:14 AUG 22, 2022 CP= 0.561 - - NODE LABEL REAL IMAG - 26 FZ -10.0000000 0.00000000 + This command is also valid in PREP7. """ command = f"LSREAD,{lsnum}" return self.run(command, **kwargs) - def lssolve(self, lsmin="", lsmax="", lsinc="", **kwargs): - """Reads and solves multiple load steps. + def lssolve(self, lsmin: str = "", lsmax: str = "", lsinc: str = "", **kwargs): + r"""Reads and solves multiple load steps. - APDL Command: LSSOLVE + Mechanical APDL Command: `LSSOLVE `_ Parameters ---------- - lsmin, lsmax, lsinc - Range of load step files to be read and solved, from - ``lsmin`` to ``lsmax`` in steps of ``lsinc``. ``lsmax`` - defaults to ``lsmin``, and ``lsinc`` defaults to 1. If - ``lsmin`` is blank, a brief command description is - displayed. The load step files are assumed to be named - Jobname.Sn, where n is a number assigned by the - ``lswrite`` command (01--09, 10, 11, etc.). On systems - with a 3-character limit on the extension, the "S" is - dropped for numbers > 99. + lsmin : str + Range of load step files to be read and solved, from ``LSMIN`` to ``LSMAX`` in steps of + ``LSINC``. ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` is blank, + a brief command description is displayed. The load step files are assumed to be named + :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01-- + 09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. + + lsmax : str + Range of load step files to be read and solved, from ``LSMIN`` to ``LSMAX`` in steps of + ``LSINC``. ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` is blank, + a brief command description is displayed. The load step files are assumed to be named + :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01-- + 09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. + + lsinc : str + Range of load step files to be read and solved, from ``LSMIN`` to ``LSMAX`` in steps of + ``LSINC``. ``LSMAX`` defaults to ``LSMIN``, and ``LSINC`` defaults to 1. If ``LSMIN`` is blank, + a brief command description is displayed. The load step files are assumed to be named + :file:`Jobname.Sn`, where ``n`` is a number assigned by the :ref:`lswrite` command (01-- + 09,10,11, etc.). On systems with a 3-character limit on the extension, the S is dropped for + numbers > 99. Notes ----- - ``lssolve`` invokes an ANSYS macro to read and solve multiple - load steps. The macro loops through a series of load step - files written by the LSWRITE command. The macro file called - by ``lssolve`` is called LSSOLVE.MAC. - ``lssolve`` cannot be used with the birth-death option. + .. _LSSOLVE_notes: - ``lssolve`` is not supported for cyclic symmetry analyses. + This command invokes a Mechanical APDL macro ( :file:`LSSOLVE.MAC` ) to read and solve multiple load + steps. - ``lssolve`` does not support restarts. + The macro loops through a series of load step files written by the :ref:`lswrite` command. - Examples - -------- - Write the load and load step option data to a file and solve - it. In this case, write the second load step. - - >>> mapdl.lswrite(2) - >>> mapdl.lssolve(1, 2) + This command cannot be used with the birth-death option, does not support cyclic symmetry analysis, + and does not support restarts. """ - return self.run(f"LSSOLVE,{lsmin},{lsmax},{lsinc}", **kwargs) + command = f"LSSOLVE,{lsmin},{lsmax},{lsinc}" + return self.run(command, **kwargs) - def lswrite(self, lsnum="", **kwargs): - """Writes load and load step option data to a file. + def lswrite(self, lsnum: str = "", **kwargs): + r"""Writes load and load step option data to a file. - APDL Command: LSWRITE + Mechanical APDL Command: `LSWRITE `_ + + .. warning:: + + This command must be run using :func:`non_interactive `. + Please visit `Unsupported Interactive Commands `_ + for further information. Parameters ---------- - lsnum - Number to be assigned to the load step file name for identification - purposes. Defaults to 1 + highest LSNUM used in the current - session. Issue LSWRITE,STAT to list the current value of LSNUM. - Issue LSWRITE,INIT to reset to 1. The load step file will be named - Jobname.Sn, where n is the specified LSNUM value (preceded by "0" - for values 1-9). On systems with a 3-character limit on the file - name extension, the "S" is dropped for LSNUM > 99. + lsnum : str + Number to be assigned to the load step file name for identification purposes. Defaults to 1 + + highest ``LSNUM`` used in the current session. Issue :ref:`lswrite`,STAT to list the current + value of ``LSNUM``. Issue :ref:`lswrite`,INIT to reset to 1. The load step file will be named + :file:`Jobname.Sn`, where ``n`` is the specified ``LSNUM`` value (preceded by "0" for values + 1-9). On systems with a 3-character limit on the file name extension, the "S" is dropped for + ``LSNUM`` > 99. Notes ----- - Writes all load and load step option data for the selected model to a - load step file for later use. LSWRITE does not capture changes made to - real constants (R), material properties (MP), couplings (CP), or - constraint equations (CE). - Solid model loads will not be saved if the model is not meshed. Solid - model loads, if any, are transferred to the finite element model. Issue - LSCLEAR,FE to delete finite element loads. + .. _LSWRITE_notes: + + Writes all load and load step option data for the selected model to a load step file for later use. + :ref:`lswrite` does not capture changes made to real constants ( :ref:`r` ), material properties ( + :ref:`mp` ), couplings ( :ref:`cp` ), or constraint equations ( :ref:`ce` ). + + Solid model loads will not be saved if the model is not meshed. Solid model loads, if any, are + transferred to the finite element model. Issue :ref:`lsclear`,FE to delete finite element loads. - One file is written for each load step. Use the LSREAD command to read - a single load step file, and the LSDELE command to delete load step - files. Use the LSSOLVE command to read and solve the load steps - sequentially. + One file is written for each load step. Use the :ref:`lsread` command to read a single load step + file, and the :ref:`lsdele` command to delete load step files. Use the :ref:`lssolve` command to + read and solve the load steps sequentially. - Solution control commands are typically not written to the file unless - you specifically change a default solution setting. + Solution control commands are typically not written to the file unless you specifically change a + default solution setting. - LSWRITE does not support the following commands: DJ, FJ, GSBDATA, - GSGDATA, ESTIF, EKILL, EALIVE, MPCHG, and OUTRES. These commands will - not be written to the load step file. + :ref:`lswrite` does not support the following commands: :ref:`dj`, :ref:`fj`, :ref:`gsbdata`, + :ref:`gsgdata`, :ref:`estif`, :ref:`ekill`, :ref:`ealive`, :ref:`mpchg`, and :ref:`outres`. These + commands will not be written to the load step file. - LSWRITE cannot be used with the birth-death option. + :ref:`lswrite` cannot be used with the birth-death option. This command is also valid in PREP7. """ diff --git a/src/ansys/mapdl/core/_commands/solution/load_step_options.py b/src/ansys/mapdl/core/_commands/solution/load_step_options.py index 0f12b9aefed..e12cd44f441 100644 --- a/src/ansys/mapdl/core/_commands/solution/load_step_options.py +++ b/src/ansys/mapdl/core/_commands/solution/load_step_options.py @@ -22,751 +22,828 @@ class LoadStepOptions: - def autots(self, key="", **kwargs): - """Specifies whether to use automatic time stepping or load stepping. - APDL Command: AUTOTS + def autots(self, key: str = "", **kwargs): + r"""Specifies whether to use automatic time stepping or load stepping. + + Mechanical APDL Command: `AUTOTS `_ Parameters ---------- - key + key : str Automatic time stepping key: - OFF - Do not use automatic time stepping. + * ``OFF`` - Do not use automatic time stepping. - ON - Use automatic time stepping (default). + * ``ON`` - Use automatic time stepping (default). - AUTO - The program determines whether to use automatic time stepping (used by - Workbench). + * ``AUTO`` - The program determines whether to use automatic time stepping (used by Workbench). Notes ----- - Specifies whether to use automatic time stepping (or load stepping) - over this load step. If Key = ON, both time step prediction and time - step bisection will be used. - - You cannot use automatic time stepping ``AUTOTS``, line search ``LNSRCH``, - or the DOF solution predictor [PRED] with the arc-length method - ``ARCLEN, ARCTRM``. If you activate the arc-length method after you set - ``AUTOTS, LNSRCH``, or ``PRED``, a warning message appears. If you choose to - proceed with the arc-length method, the program disables your automatic - time stepping, line search, and DOF predictor settings, and the time - step size is controlled by the arc-length method internally. + + .. _AUTOTS_notes: + + Specifies whether to use automatic time stepping (or load stepping) over this load step. If ``Key`` + = ON, both time step prediction and time step bisection will be used. + + Bisection does not occur with :ref:`thopt`,QUASI since it uses only one equilibrium iteration per + substep. To ensure bisection, use the iterative QUASI method ( :ref:`thopt`,QUASI,,,,,,1). + + You cannot use automatic time stepping ( :ref:`autots` ), line search ( :ref:`lnsrch` ), or the DOF + solution predictor ( :ref:`pred` ) with the arc-length method ( :ref:`arclen`, :ref:`arctrm` ). If + you activate the arc-length method after you set :ref:`autots`, :ref:`lnsrch`, or :ref:`pred`, a + warning message appears. If you choose to proceed with the arc-length method, the program disables + your automatic time stepping, line search, and DOF predictor settings, and the time step size is + controlled by the arc-length method internally. This command is also valid in PREP7. """ command = f"AUTOTS,{key}" return self.run(command, **kwargs) - def campbell(self, action="", **kwargs): - """Prepares the result file for a subsequent Campbell diagram of a + def campbell(self, action: str = "", **kwargs): + r"""Prepares the result file for a subsequent Campbell diagram of a prestressed structure. - APDL Command: CAMPBELL - prestressed structure. + Mechanical APDL Command: `CAMPBELL `_ Parameters ---------- - action + action : str Campbell action: - NONE - Do not prepare the result file. This option is the default behavior. + * ``NONE`` - Do not prepare the result file. This option is the default behavior. - RSTP - Prepare the result file (Jobname.RSTP) for a subsequent Campbell diagram of a - prestressed structure. + * ``RSTP`` - Prepare the result file ( :file:`Jobname.RSTP` ) for a subsequent `Campbell diagram + `_ + of a prestressed structure. Notes ----- - For an analysis involving a prestressed structure, the ``CAMPBELL`` command - specifies whether or not to prepare the result file to support a - Campbell diagram analysis (``PRCAMP`` or ``PLCAMP``). - - To prestress a structure, the program performs a static solution before - the linear perturbation modal solution. - - The CAMPBELL command requires that modal and static analyses be - performed alternately. It works only when the number of static analyses - is the same as the number of modal analyses. Any number of analyses can - be performed, but the same number of each (static and modal) is - expected. The modal solutions are appended in the results file - (Jobname.RSTP). - - For an example of PLCAMP command usage, see Example Campbell Diagram - Analysis in the Advanced Analysis Guide. + For an analysis involving a prestressed structure, the :ref:`campbell` command specifies whether or + not to prepare the result file to support a `Campbell diagram + `_ + analysis ( :ref:`prcamp` or :ref:`plcamp` ). + + To prestress a structure, the program performs a static solution before the `linear perturbation + `_ modal + solution. For specific information about rotating structures, see `Considerations for Rotating + Structures + `_ + + The :ref:`campbell` command requires that modal and static analyses be performed alternately. It + works only when the number of static analyses is the same as the number of modal analyses. Any + number of analyses can be performed, but the same number of each (static and modal) is expected. The + modal solutions are appended in the results file ( :file:`Jobname.RSTP` ). + + For an example of :ref:`campbell` command usage, see in the `Rotordynamic Analysis Guide + `_. """ command = f"CAMPBELL,{action}" return self.run(command, **kwargs) - def cecmod(self, neqn="", const="", **kwargs): - """Modifies the constant term of a constraint equation during solution. + def cecmod(self, neqn: str = "", const: str = "", **kwargs): + r"""Modifies the constant term of a constraint equation during solution. - APDL Command: CECMOD + Mechanical APDL Command: `CECMOD `_ Parameters ---------- - neqn + neqn : str Reference number of constraint equation. - const + const : str New value of the constant term of equation. Notes ----- - Other terms of the constraint equation cannot be changed during the - solution phase, but must be defined or changed within PREP7 prior to - the solution. See the CE command for details. + + .. _CECMOD_notes: + + Other terms of the constraint equation cannot be changed during the solution phase, but must be + defined or changed within PREP7 prior to the solution. See the :ref:`ce` command for details. This command is also valid in PREP7. """ command = f"CECMOD,{neqn},{const}" return self.run(command, **kwargs) - def deltim(self, dtime="", dtmin="", dtmax="", carry="", **kwargs): - """Specifies the time step sizes to be used for the current load step. + def deltim( + self, + dtime: str = "", + dtmin: str = "", + dtmax: str = "", + carry: str = "", + **kwargs, + ): + r"""Specifies the time step sizes to be used for the current load step. - APDL Command: DELTIM + Mechanical APDL Command: `DELTIM `_ Parameters ---------- - dtime - Time step size for this step. If automatic time stepping is used - (AUTOTS), DTIME is the starting time substep. + dtime : str + Time step size for this step. If automatic time stepping is used ( :ref:`autots` ), ``DTIME`` is + the starting time substep. - dtmin - Minimum time step (if automatic time stepping is used). The program - automatically determines the default based on the physics of the - model. + If contact elements ( ``TARGE169``, ``TARGE170``, ``CONTA172``, ``CONTA174``, ``CONTA175``, or + ``CONTA177`` ) are used, defaults to ``TIME`` or ``TIME`` /20 (where ``TIME`` is the time at the + end of the load step as set on the :ref:`time` command), depending on the physics of the model. + If none of these contact elements are used, defaults to ``TIME``. - dtmax - Maximum time step (if automatic time stepping is used). The program - automatically determines the default based on the physics of the - model. + dtmin : str + Minimum time step (if automatic time stepping is used). The program automatically determines the + default based on the physics of the model. - carry + dtmax : str + Maximum time step (if automatic time stepping is used). The program automatically determines the + default based on the physics of the model. + + carry : str Time step carry over key: - OFF - Use DTIME as time step at start of each load step. + * ``OFF`` - Use ``DTIME`` as time step at start of each load step. + + * ``ON`` - Use final time step from previous load step as the starting time step (if automatic time + stepping is used). - ON - Use final time step from previous load step as the starting time step (if - automatic time stepping is used). + The program automatically determines the default based on the physics of the model. Notes ----- - See NSUBST for an alternative input. - Use consistent values for DTIME and TIME (TIME). For example, using 0.9 - for DTIME and 1.0 for TIME results in one time step because 1.0 (TIME) - is divisible by .9 (DTIME) at most once. If you intend to load in 10 - increments over a time span of 1.0, use 0.1 for DTIME and 1.0 for TIME. + .. _DELTIM_notes: + + See :ref:`nsubst` for an alternative input. + + Use consistent values for ``DTIME`` and ``TIME`` ( :ref:`time` ). For example, using 0.9 for + ``DTIME`` and 1.0 for ``TIME`` results in one time step because 1.0 ( ``TIME`` ) is divisible by.9 + ( ``DTIME`` ) at most once. If you intend to load in 10 increments over a time span of 1.0, use 0.1 + for ``DTIME`` and 1.0 for ``TIME``. - The program calculates the initial incremental time so that (EndingTime - - StartingTime)/DTIME is an integer, which may affect the initial - incremental time that you specify. For example, if the starting time is - 0, the ending time is 1, and the initial incremental time is 0.4, the - program rounds to the nearest integer and adjusts the time to 0.33333. + The program calculates the initial incremental time so that ( ``EndingTime`` - ``StartingTime`` )/ + ``DTIME`` is an integer, which may affect the initial incremental time that you specify. For + example, if the starting time is 0, the ending time is 1, and the initial incremental time is 0.4, + the program rounds to the nearest integer and adjusts the time to 0.33333. For solution efficiency, specify values for all fields of this command. + Changing the time step size upon restarting an analysis during a load step is not recommended. You + should only change the time step size between load steps. + This command is also valid in PREP7. """ command = f"DELTIM,{dtime},{dtmin},{dtmax},{carry}" return self.run(command, **kwargs) - def expsol(self, lstep="", sbstep="", timfrq="", elcalc="", **kwargs): - """Specifies the solution to be expanded for mode-superposition analyses + def expsol( + self, + lstep: str = "", + sbstep: str = "", + timfrq: str = "", + elcalc: str = "", + **kwargs, + ): + r"""Specifies the solution to be expanded for mode-superposition analyses or substructure analyses. - APDL Command: EXPSOL - or substructure analyses. + Mechanical APDL Command: `EXPSOL `_ Parameters ---------- - lstep, sbstep - Expand the solution identified as load step LSTEP and substep - SBSTEP. + lstep : str + Expand the solution identified as load step ``LSTEP`` and substep ``SBSTEP``. - timfrq - As an alternative to LSTEP and SBSTEP, expand the solution at, or - nearest to, the time value TIMFRQ (for ANTYPE,TRANS or - ANTYPE,SUBSTR) or frequency value TIMFRQ (for ANTYPE,HARMIC). - LSTEP and SBSTEP should be blank. + sbstep : str + Expand the solution identified as load step ``LSTEP`` and substep ``SBSTEP``. - elcalc + timfrq : str + As an alternative to ``LSTEP`` and ``SBSTEP``, expand the solution at, or nearest to, the time + value TIMFRQ (for :ref:`antype`,TRANS or :ref:`antype`,SUBSTR) or frequency value ``TIMFRQ`` + (for :ref:`antype`,HARMIC). ``LSTEP`` and ``SBSTEP`` should be blank. + + elcalc : str Element calculation key: - YES - Calculate element results, nodal loads, and reaction loads. + * ``YES`` - Calculate element results, nodal loads, and reaction loads. - NO - Do not calculate these items. + * ``NO`` - Do not calculate these items. Notes ----- - Specifies the solution to be expanded from analyses that use the mode- - superposition method (ANTYPE,HARMIC or TRANS) or substructuring - (ANTYPE,SUBSTR). Use the NUMEXP command to expand a group of solutions. - The resulting results file will maintain the same load step, substep, - and time (or frequency) values as the requested solution to be - expanded. + .. _EXPSOL_notes: + + Specifies the solution to be expanded from analyses that use the mode-superposition method ( + :ref:`antype`,HARMIC or TRANS) or substructuring ( :ref:`antype`,SUBSTR). Use the :ref:`numexp` + command to expand a group of solutions. + + The resulting results file will maintain the same load step, substep, and time (or frequency) values + as the requested solution to be expanded. This command is also valid in PREP7. """ command = f"EXPSOL,{lstep},{sbstep},{timfrq},{elcalc}" return self.run(command, **kwargs) - def kbc(self, key="", **kwargs): - """Specifies ramped or stepped loading within a load step. + def kbc(self, key: int | str = "", omgsqrdkey: int | str = "", **kwargs): + r"""Specifies ramped or stepped loading within a load step. - APDL Command: KBC + Mechanical APDL Command: `KBC `_ Parameters ---------- - key + key : int or str Ramping key: - 0 - Loads are linearly interpolated (ramped) for each substep from the values of - the previous load step to the values of this load step. This is - the default value. + * ``0`` - Loads are linearly interpolated (ramped) for each substep from the values of the previous + load step to the values of this load step. This is the default value. + + * ``1`` - Loads are step changed (stepped) at the first substep of this load step to the values of + this load step (that is, the same values are used for all substeps). Useful for rate-dependent + behavior (for example, creep, viscoplasticity, etc.) or transient load steps only. - 1 - Loads are step changed (stepped) at the first substep of this load step to the - values of this load step (i.e., the same values are used for - all substeps). Useful for rate-dependent behavior (e.g., - creep, viscoplasticity, etc.) or transient load steps only. + omgsqrdkey : int or str + Key for the interpolation of the rotational velocity loading (only supported when ``KEY`` = 0): + + * ``0`` - Rotational velocities are linearly interpolated. This is the default. + + * ``1`` - A quadratic interpolation is used for the rotational velocities ( :ref:`omega`, + :ref:`cmomega`, and :ref:`cmrotate` ). All other loads are interpolated linearly. Notes ----- - Specifies whether loads applied to intermediate substeps within the - load step are to be stepped or ramped. Used only if DTIME on the DELTIM - command is less than the time span or, conversely, if NSBSTP on the - NSUBST command is greater than one. Flags (FSI, MXWF, MVDI, etc.) are - always stepped. - - Changing the ramping KEY (i.e., switching between ramped and stepped - boundary conditions) between load steps is not recommended. - - For ramped loading (KBC,0), when a load is applied for the first time, - it is interpolated from zero to the value of the current load step, and - not from the initial condition or value of the degree of freedom from - the previous load step. - - Spatially varying tabular loads or boundary conditions do not support - direct ramping or stepping options and, instead, apply their full - values according to the supplied tabular functions regardless of the - KBC setting. - - For a static or harmonic cyclic symmetry analysis, any load that varies - by sector (CYCOPT,LDSECT) is tabular and is applied as a step change, - regardless of the KBC setting; however, any non-tabular loads in the - same analysis are ramped or stepped according to the KBC setting. - - Irrespective of the KBC setting, loads are usually step-removed. See - Stepping or Ramping Loads in the Basic Analysis Guide for more + + .. _KBC_notes: + + Specifies whether loads applied to intermediate substeps within the load step are to be stepped or + ramped. Used only if ``DTIME`` on the :ref:`deltim` command is less than the time span or, + conversely, if ``NSBSTP`` on the :ref:`nsubst` command is greater than one. Flags (FSI, MXWF, MVDI, + etc.) are always stepped. + + Changing the ramping ``KEY`` (that is, switching between ramped and stepped boundary conditions) + between load steps is not recommended. + + For ramped loading ( :ref:`kbc`,0), when a load is applied for the first time, it is interpolated + from zero to the value of the current load step, and not from the initial condition or value of the + degree of freedom from the previous load step. + + Spatially varying tabular loads or boundary conditions do not support direct ramping or stepping + options and, instead, apply their full values according to the supplied tabular functions regardless + of the :ref:`kbc` setting. + + Regardless of the :ref:`kbc` setting, any tabular load is applied as step change. This is the case, + for example, for a static or harmonic cyclic symmetry analysis with a load that varies by sector ( + :ref:`cycopt`, LDSECT). Note that when tabular and non-tabular loads are present in the same + analysis, the non-tabular loads are ramped or stepped according to the :ref:`kbc` setting. + + Irrespective of the :ref:`kbc` setting, loads are usually step-removed. See `Stepping or Ramping + Loads + `_ + in the `Basic Analysis Guide + `_ for more information. - It is sometimes difficult to obtain successful convergence with stepped - loading in a nonlinear transient problem. If divergence is encountered, - determine if stepped loading was used by default, then determine if it - is appropriate for the analysis. + It is sometimes difficult to obtain successful convergence with stepped loading in a nonlinear + transient problem. If divergence is encountered, determine if stepped loading was used by default, + then determine if it is appropriate for the analysis. This command is also valid in PREP7. """ - command = f"KBC,{key}" + command = f"KBC,{key},{omgsqrdkey}" return self.run(command, **kwargs) - def kuse(self, key="", **kwargs): - """Specifies whether or not to reuse the factorized matrix. + def kuse(self, key: int | str = "", **kwargs): + r"""Specifies whether or not to reuse factorized matrices. - APDL Command: KUSE + Mechanical APDL Command: `KUSE `_ Parameters ---------- - key + key : int or str Reuse key: - - 0 : Program decides whether or not to reuse the previous - factorized stiffness matrix. - - 1 : Force the previous factorized stiffness matrix to be - reused. Used mainly in a restart. Forcing reuse of the - matrix is a nonstandard use of the program, and - should be done with caution. For instance, using - this option and changing the number of elements, or - the number or type of degrees of freedom, may cause - an abort. - - -1 : All element matrices are reformed and are used to - reform a new factorized stiffness matrix. + * ``0`` - Program decides whether or not to reuse the previous factorized matrices. + + * ``1`` - Force the previous factorized matrices to be reused. Used mainly in a restart. Forcing + reuse of the matrices is a nonstandard use of the program and should be done with caution. For + instance, using this option and changing the number of elements, or the number or type of degrees of + freedom, may cause an abort. + + * ``-1`` - All element matrices are reformed and are used to reform new factorized matrices. Notes ----- - Overrides the program logic to determine whether or not to reuse the - previous factorized stiffness matrix for each substep of this load - step. Applies only to static or full transient analyses and to full - harmonic analyses if the frequency is not changed for continuing - loadsteps. For full harmonic analyses, only KEY = 1 or KEY = 0 is - valid. + + .. _KUSE_notes: + + Overrides the program logic to determine whether or not to reuse the previous factorized matrices + for each substep of this load step. Applies only to static or full transient analyses. For more + details see. This command is also valid in PREP7. """ command = f"KUSE,{key}" return self.run(command, **kwargs) - def magopt(self, value="", **kwargs): - """Specifies options for a 3-D magnetostatic field analysis. + def magopt(self, value: int | str = "", **kwargs): + r"""Specifies options for a 3D magnetostatic field analysis. - APDL Command: MAGOPT + Mechanical APDL Command: `MAGOPT `_ Parameters ---------- - value + value : int or str Option key: - 0 - Calculate a complete H field solution in the entire domain using a single - (reduced) potential. + * ``0`` - Calculate a complete H field solution in the entire domain using a single (reduced) potential. + + .. warning:: - Caution:When used in problems with both current sources and iron regions, errors may result due to numerical cancellation. - 1 + When used in problems with both current sources and iron regions, errors may result due to + numerical cancellation. + * ``1`` - Calculate and store a preliminary H field in "iron" regions (μ:sub:`r` ≠ 1). Requires + flux-parallel boundary conditions to be specified on exterior iron boundaries. Used in conjunction + with subsequent solutions with ``VALUE`` = 2 followed by ``VALUE`` = 3. Applicable to multiply- + connected iron domain problems. - Calculate and store a preliminary H field in "iron" regions (μr ≠ 1). Requires flux-parallel boundary conditions to be specified on exterior iron boundaries. Used in conjunction with subsequent solutions with VALUE = 2 followed by VALUE = 3. Applicable to multiply-connected iron domain problems. - 2 + * ``2`` - Calculate and store a preliminary H field in "air" regions (μ:sub:`r` = 1). The air-iron + interface is appropriately treated internally by the program. Used in conjunction with a subsequent + solution with ``VALUE`` = 3. Applicable to singly-connected iron domain problems (with subsequent + solution with ``VALUE`` = 3) or to multiply-connected iron domain problems (when preceded by a + solution with ``VALUE`` = 1 and followed by a solution with ``VALUE`` = 3). - Calculate and store a preliminary H field in "air" regions (μr = 1). The air-iron interface is appropriately treated internally by the program. Used in conjunction with a subsequent solution with VALUE = 3. Applicable to singly-connected iron domain problems (with subsequent solution with VALUE = 3) or to multiply-connected iron domain problems (when preceded by a solution with VALUE = 1 and followed by a solution with VALUE = 3). - 3 + * ``3`` - Use the previously stored H field solution(s) and calculate the complete H field. Notes ----- - Specifies the solution sequence options for a 3-D magnetostatic field - analysis using a scalar potential (MAG). The solution sequence is - determined by the nature of the problem. - You cannot use constraint equations with Value = 1. + .. _MAGOPT_notes: + + Specifies the solution sequence options for a 3D magnetostatic field analysis using a scalar + potential (MAG). The solution sequence is determined by the nature of the problem. + + You cannot use constraint equations with ``Value`` = 1. This command is also valid in PREP7. - Distributed ANSYS Restriction: The MAGOPT,3 option is not supported in - Distributed ANSYS when the following contact elements are present in - the model: CONTA173, CONTA174, CONTA175, CONTA176, or CONTA177. + Distributed-Memory Parallel (DMP) Restriction :ref:`magopt`,3 is not supported in a DMP solution + when the following contact elements are present + in the model: ``CONTA174``, ``CONTA175``, or ``CONTA177``. """ command = f"MAGOPT,{value}" return self.run(command, **kwargs) def magsolv( self, - opt="", - nramp="", - cnvcsg="", - cnvflux="", - neqit="", - biot="", - cnvtol="", + opt: int | str = "", + nramp: str = "", + cnvcsg: str = "", + cnvflux: str = "", + neqit: str = "", + biot: int | str = "", + cnvtol: str = "", **kwargs, ): - """Specifies magnetic solution options and initiates the solution. + r"""Specifies magnetic solution options and initiates the solution. - APDL Command: MAGSOLV + Mechanical APDL Command: `MAGSOLV `_ Parameters ---------- - opt + opt : int or str Static magnetic solution option: - 0 - Vector potential (MVP) or edge formulation (default). + * ``0`` - Vector potential (MVP) or edge formulation (default). - 1 - Combined vector potential and reduced scalar potential (MVP-RSP). + * ``1`` - Combined vector potential and reduced scalar potential (MVP-RSP). - 2 - Reduced scalar potential (RSP). + * ``2`` - Reduced scalar potential (RSP). - 3 - Difference scalar potential (DSP). + * ``3`` - Difference scalar potential (DSP). - 4 - General scalar potential (GSP). + * ``4`` - General scalar potential (GSP). - nramp - Number of ramped substeps for the first load step of a nonlinear - MVP or MVP-RSP solution. Defaults to 3. If NRAMP = -1, ignore the - ramped load step entirely.NRAMP is ignored for linear - magnetostatics. + nramp : str + Number of ramped substeps for the first load step of a nonlinear MVP or MVP-RSP solution. + Defaults to 3. If ``NRAMP`` = -1, ignore the ramped load step entirely. ``NRAMP`` is ignored for + linear magnetostatics. - cnvcsg - Tolerance value on the program-calculated reference value for the - magnetic current-segment convergence. Used for the MVP, the MVP- - RSP, and the edge formulation solution options (OPT = 0 and 1). - Defaults to 0.001. + cnvcsg : str + Tolerance value on the program-calculated reference value for the magnetic current-segment + convergence. Used for the MVP, the MVP-RSP, and the edge formulation solution options ( ``OPT`` + = 0 and 1). Defaults to 0.001. - cnvflux - Tolerance value on the program-calculated reference value for the - magnetic flux convergence. Used for all scalar potential solution - options (OPT = 2, 3, 4). Defaults to 0.001. + cnvflux : str + Tolerance value on the program-calculated reference value for the magnetic flux convergence. + Used for all scalar potential solution options ( ``OPT`` = 2, 3, 4). Defaults to 0.001. - neqit - Maximum number of equilibrium iterations per load step. Defaults - to 25. + neqit : str + Maximum number of equilibrium iterations per load step. Defaults to 25. - biot - Option to force execution of a Biot-Savart integral solution - [BIOT,NEW] for the scalar potential options. Required if multiple - load steps are being performed with different current source - primitives (SOURC36 elements). + biot : int or str + Option to force execution of a Biot-Savart integral solution ( :ref:`biot`,NEW) for the scalar potential options. Required if multiple load steps are being performed with different current source primitives ( ``SOURC36`` elements). - 0 - Do not force execution of Biot-Savart calculation (default); Biot-Savart is - automatically calculated only for the first solution. + * ``0`` - Do not force execution of Biot-Savart calculation (default); Biot-Savart is automatically + calculated only for the first solution. - 1 - Force execution of Biot-Savart calculation. + * ``1`` - Force execution of Biot-Savart calculation. - cnvtol + cnvtol : str Sets the convergence tolerance for AMPS reaction. Defaults to 1e-3. Notes ----- - MAGSOLV invokes an ANSYS macro which specifies magnetic solution - options and initiates the solution. The macro is applicable to any - ANSYS magnetostatic analysis using the magnetic vector potential (MVP), - reduced scalar potential (RSP), difference scalar potential (DSP), - general scalar potential (GSP), or combined MVP-RSP formulation - options. Results are only stored for the final converged solution. - (In POST1, issue ``*SET,LIST`` to identify the load step of solution - results.) The macro internally determines if a nonlinear analysis is - required based on magnetic material properties. - - If you use the BIOT option and issue SAVE after solution or - postprocessing, the Biot-Savart calculations are saved to the database, - but will be overwritten upon normal exit from the program. To save - this data after issuing SAVE, use the /EXIT,NOSAVE command. You can - also issue the /EXIT,SOLU command to exit ANSYS and save all solution - data, including the Biot-Savart calculations, in the database. - Otherwise, when you issue RESUME, the Biot-Savart calculation will be - lost (resulting in a zero solution). - - The MVP, MVP-RSP, and edge formulation options perform a two-load-step - solution sequence. The first load step ramps the applied loads over a - prescribed number of substeps (NRAMP), and the second load step - calculates the converged solution. For linear problems, only a single - load step solution is performed. The ramped load step can be bypassed - by setting NRAMP to -1. - - The RSP option solves in a single load step using the adaptive descent - procedure. The DSP option uses two load steps, and the GSP solution - uses three load steps. - - The following analysis options and nonlinear options are controlled by - this macro: KBC, NEQIT, NSUBST, CNVTOL, NROPT, MAGOPT, and OUTRES. - - You cannot use constraint equations with OPT = 4. + + .. _MAGSOLV_notes: + + :ref:`magsolv` invokes a Mechanical APDL macro which specifies magnetic solution options and + initiates the + solution. The macro is applicable to any Mechanical APDL magnetostatic analysis using the magnetic + vector + potential (MVP), reduced scalar potential (RSP), difference scalar potential (DSP), general scalar + potential (GSP), or combined MVP-RSP formulation options. Results are only stored for the final + converged solution. (In POST1, issue :ref:`starset`,LIST to identify the load step of solution + results.) The macro internally determines if a nonlinear analysis is required based on magnetic + material properties. + + If you use the ``BIOT`` option and issue :ref:`save` after solution or postprocessing, the Biot- + Savart calculations are saved to the database, but will be overwritten upon normal exit from the + program. To save this data after issuing :ref:`save`, use the ``/EXIT``,NOSAVE command. You can + also issue the ``/EXIT``,SOLU command to exit Mechanical APDL and save all solution data, including + the + Biot-Savart calculations, in the database. Otherwise, when you issue :ref:`resume`, the Biot-Savart + calculation will be lost (resulting in a zero solution). + + The MVP, MVP-RSP, and edge formulation options perform a two-load-step solution sequence. The first + load step ramps the applied loads over a prescribed number of substeps ( ``NRAMP`` ), and the second + load step calculates the converged solution. For linear problems, only a single load step solution + is performed. The ramped load step can be bypassed by setting ``NRAMP`` to -1. + + The RSP option solves in a single load step using the adaptive descent procedure. The DSP option + uses two load steps, and the GSP solution uses three load steps. + + The following analysis options and nonlinear options are controlled by this macro: :ref:`kbc`, + :ref:`neqit`, :ref:`nsubst`, :ref:`cnvtol`, :ref:`nropt`, :ref:`magopt`, and :ref:`outres`. + + You cannot use constraint equations with ``OPT`` = 4. + + When the ``BIOT`` option is on ( ``BIOT`` = 1), Distributed-Memory Parallel (DMP) restrictions may + apply. For more information, see the :ref:`biot` command. """ command = f"MAGSOLV,{opt},{nramp},{cnvcsg},{cnvflux},{neqit},{biot},{cnvtol}" return self.run(command, **kwargs) - def mode(self, mode="", isym="", **kwargs): - """Specifies the harmonic loading term for this load step. + def mode(self, mode: str = "", isym: int | str = "", **kwargs): + r"""Specifies the harmonic loading term for this load step. - APDL Command: MODE + Mechanical APDL Command: `MODE `_ Parameters ---------- - mode - Number of harmonic waves around circumference for this harmonic - loading term (defaults to 0). + mode : str + Number of harmonic waves around circumference for this harmonic loading term (defaults to 0). - isym - Symmetry condition for this harmonic loading term (not used when - MODE = 0): + isym : int or str + Symmetry condition for this harmonic loading term (not used when ``MODE`` = 0): - 1 - Symmetric (UX, UY, ROTZ, TEMP use cosine terms; UZ uses sine term) (default). + * ``1`` - Symmetric (UX, UY, ROTZ, TEMP use cosine terms; UZ uses sine term) (default). - -1 - Antisymmetric (UX, UY, ROTZ, TEMP use sine terms; UZ uses cosine term). + * ``-1`` - Antisymmetric (UX, UY, ROTZ, TEMP use sine terms; UZ uses cosine term). Notes ----- - Used with axisymmetric elements having nonaxisymmetric loading - capability (for example, PLANE25, SHELL61, etc.). For analysis types - ANTYPE,MODAL, HARMIC, TRANS, and SUBSTR, the term must be defined in - the first load step and may not be changed in succeeding load steps. + + .. _MODE_notes: + + Used with axisymmetric elements having nonaxisymmetric loading capability (for example, ``PLANE25``, + ``SHELL61``, etc.). For analysis types :ref:`antype`,MODAL, HARMIC, TRANS, and SUBSTR, the term must + be defined in the first load step and may not be changed in succeeding load steps. This command is also valid in PREP7. """ command = f"MODE,{mode},{isym}" return self.run(command, **kwargs) - def nsubst(self, nsbstp="", nsbmx="", nsbmn="", carry="", **kwargs): - """Specifies the number of substeps to be taken this load step. + def nsubst( + self, + nsbstp: str = "", + nsbmx: str = "", + nsbmn: str = "", + carry: str = "", + **kwargs, + ): + r"""Specifies the number of substeps to be taken this load step. - APDL Command: NSUBST + Mechanical APDL Command: `NSUBST `_ Parameters ---------- - nsbstp - Number of substeps to be used for this load step (i.e., the time - step size or frequency increment). If automatic time stepping is - used (``AUTOTS``), ``NSBSTP`` defines the size of the first substep. + nsbstp : str + Number of substeps to be used for this load step (that is, the time step size or frequency + increment). If automatic time stepping is used ( :ref:`autots` ), ``NSBSTP`` defines the size of + the first substep. + + If contact elements ( ``TARGE169``, ``TARGE170``, ``CONTA172``, ``CONTA174``, ``CONTA175``, or + ``CONTA177`` ) are used, defaults to 1 or 20 substeps, depending on the physics of the model. If + none of these contact elements are used, defaults to 1 substep. + + nsbmx : str + Maximum number of substeps to be taken (that is, the minimum time step size) if automatic time + stepping is used. The program automatically determines the default based on the physics of the + model. - nsbmx - Maximum number of substeps to be taken (i.e., the minimum time step - size) if automatic time stepping is used. The program automatically - determines the default based on the physics of the model. + nsbmn : str + Minimum number of substeps to be taken (that is, the maximum time step size) if automatic time + stepping is used. The program automatically determines the default based on the physics of the + model. - nsbmn - Minimum number of substeps to be taken (i.e., the maximum time step - size) if automatic time stepping is used. The program automatically - determines the default based on the physics of the model. + carry : str + Time step carryover key (program-determined default depending on the problem physics): - carry - Time step carryover key (program-determined default depending on - the problem physics): + * ``OFF`` - Use ``NSBSTP`` to define time step at start of each load step. - OFF - Use NSBSTP to define time step at start of each load step. + * ``ON`` - Use final time step from previous load step as the starting time step (if automatic time + stepping is used). - ON - Use final time step from previous load step as the starting time step (if - automatic time stepping is used). + The program automatically determines the default based on the physics of the model. Notes ----- - See ``DELTIM`` for an alternative input. It is recommended that all fields - of this command be specified for solution efficiency and robustness. - When the arc-length method is active (``ARCLEN`` command), the ``NSBMX`` and - ``NSBMN`` arguments are ignored. + .. _NSUBST_notes: + + See :ref:`deltim` for an alternative input. It is recommended that all fields of this command be + specified for solution efficiency and robustness. + + When the arc-length method is active ( :ref:`arclen` command), the ``NSBMX`` and ``NSBMN`` arguments + are ignored. + + Changing the number of substeps upon restarting an analysis during a load step is not recommended. + You should only change the number of substeps between load steps. This command is also valid in PREP7. """ command = f"NSUBST,{nsbstp},{nsbmx},{nsbmn},{carry}" return self.run(command, **kwargs) - def numexp(self, num="", begrng="", endrng="", elcalc="", **kwargs): - """Specifies solutions to be expanded from mode-superposition analyses or + def numexp( + self, + num: str = "", + begrng: str = "", + endrng: str = "", + elcalc: str = "", + **kwargs, + ): + r"""Specifies solutions to be expanded from mode-superposition analyses or substructure analyses. - APDL Command: NUMEXP - substructure analyses. + Mechanical APDL Command: `NUMEXP `_ Parameters ---------- - num + num : str The number of solutions to expand. This value is required. - Num - Number of solutions to expand. + * ``Num`` - Number of solutions to expand. - ALL - Expand all substeps between ``BEGRNG`` and ``ENDRNG`` (provided that ENDRNG > 0). If - ``BEGRNG`` and ``ENDRNG`` have no specified values, this option - expands all substeps of all load steps. + * ``ALL`` - Expand all substeps between ``BEGRNG`` and ``ENDRNG`` (provided that ``ENDRNG`` > 0). If + ``BEGRNG`` and ``ENDRNG`` have no specified values, this option expands all substeps of all load + steps. - begrng, endrng - Beginning and ending time (or frequency) range for expanded - solutions. The default is 0 for both values. + begrng : str + Beginning and ending time (or frequency) range for expanded solutions. The default is 0 for both + values. - elcalc + endrng : str + Beginning and ending time (or frequency) range for expanded solutions. The default is 0 for both + values. + + elcalc : str The element-calculation key: - YES - Calculate element results, nodal loads, and reaction loads. This value is the - default. + * ``YES`` - Calculate element results, nodal loads, and reaction loads. This value is the default. - NO - Do not calculate these items. + * ``NO`` - Do not calculate these items. Notes ----- - Specifies a range of solutions to be expanded from analyses that use - mode-superposition methods (``ANTYPE,HARMIC`` or ``TRANS``) or substructuring - (``ANTYPE,SUBSTR``). + **Command Defaults** + + .. _NUMEXP_defaults: - For ANTYPE,TRANS, NUM, evenly spaced solutions are expanded between - time BEGRNG and time ``ENDRNG``. + Issuing this command with no arguments is invalid. You must specify the number of solutions, or all + solutions, to expand ( ``NUM`` ). The default value for both the beginning ( ``BEGRNG`` ) and ending + ( ``ENDRNG`` ) time or frequency is 0. The default behavior of the command is to calculate element + results, nodal loads, and reaction loads ( ``Elcalc`` = YES). - For ANTYPE,HARMIC, NUM, evenly spaced solutions are expanded between - frequency BEGRNG and frequency ``ENDRNG``. + .. _NUMEXP_notes: - The first expansion in all cases is done at the first point beyond - BEGRNG (that is, at ``BEGRNG + (ENDRNG - BEGRNG) / NUM``)). + Specifies a range of solutions to be expanded from analyses that use mode-superposition methods ( + :ref:`antype`,HARMIC or TRANS) or substructuring ( :ref:`antype`,SUBSTR). - The resulting results file will maintain the same load step, substep, - and time (or frequency) values as the use pass. + For :ref:`antype`,TRANS, ``NUM``, evenly spaced solutions are expanded between time ``BEGRNG`` and + time ``ENDRNG``. - For a single expansion of a solution, or for multiple expansions when - the solutions are not evenly spaced (such as in a mode-superposition - harmonic analysis with the cluster option), ANSYS, Inc. recommends - issuing one or more ``EXPSOL`` commands. + For :ref:`antype`,HARMIC, ``NUM``, evenly spaced solutions are expanded between frequency ``BEGRNG`` + and frequency ``ENDRNG``. - The NUMEXP command is invalid in these cases: + The first expansion in all cases is done at the first point beyond ``BEGRNG`` (that is, at + ``BEGRNG`` + ( ``ENDRNG`` - ``BEGRNG`` ) / ``NUM`` )). - In a substructing analysis (``ANTYPE,SUBST``) when a factorized matrix file - (the ``.LN22`` file generated by the sparse solver) does not exist, causing - ANSYS to employ the full-resolve method. + The resulting results file will maintain the same load step, substep, and time (or frequency) values + as the use pass. - If the full-resolve option is selected using the ``SEOPT`` command. + For a single expansion of a solution, or for multiple expansions when the solutions are not evenly + spaced (such as in a mode-superposition harmonic analysis with the cluster option), + Ansys, Inc. recommends issuing one or more :ref:`expsol` commands. - In both situations, use the ``EXPSOL`` command to perform a single - expansion for each solution desired. + :ref:`numexp` is invalid in these cases: + + * In a substructing analysis ( :ref:`antype`, ``SUBST`` ) when a factorized matrix file (the + :file:`.LN22` file generated by the sparse solver) does not exist, causing Mechanical APDL to use the + full- resolve method. + + * If the full-resolve option is selected ( :ref:`seopt` ). + + In both situations, issue :ref:`expsol` to perform a single expansion for each solution desired. This command is also valid in PREP7. """ command = f"NUMEXP,{num},{begrng},{endrng},{elcalc}" return self.run(command, **kwargs) - def time(self, time="", **kwargs): - """Sets the time for a load step. + def time(self, time: str = "", **kwargs): + r"""Sets the time for a load step. - APDL Command: TIME + Mechanical APDL Command: `TIME `_ Parameters ---------- - time + time : str Time at the end of the load step. Notes ----- - Associates the boundary conditions at the end of the load step with a - particular TIME value. - TIME must be a positive, nonzero, monotonically increasing quantity - that "tracks" the input history. Units of time should be consistent - with those used elsewhere (for properties, creep equations, etc.). + .. _TIME_notes: + + Associates the boundary conditions at the end of the load step with a particular ``TIME`` value. - Typically, for the first load step TIME defaults to 1. However, for the - first load step of a mode-superposition transient analysis - (ANTYPE,TRANS and TRNOPT,MSUP), the TIME command is ignored and a - static solution is performed at TIME = 0. + ``TIME`` must be a positive, nonzero, monotonically increasing quantity that "tracks" the input + history. Units of time should be consistent with those used elsewhere (for properties, creep + equations, etc.). - For a full transient analyses, the command's default behavior does not - apply. You must specify a time for each load step and it must be - greater than the time at the end of the prior load step. + Typically, for the first load step ``TIME`` defaults to 1. However, for the first load step of a + mode-superposition transient analysis ( :ref:`antype`,TRANS and :ref:`trnopt`,MSUP), the + :ref:`time` command is ignored and a static solution is performed at ``TIME`` = 0. - TIME does not apply to modal (ANTYPE,MODAL), harmonic (ANTYPE,HARMIC), - or substructure (ANTYPE,SUBSTR) analyses. + For a full transient analyses, the command's default behavior does not apply. You must specify a + time for each load step and it must be greater than the time at the end of the prior load step. + + ``TIME`` does not apply to modal ( :ref:`antype`,MODAL), harmonic ( :ref:`antype`,HARMIC), or + substructure ( :ref:`antype`,SUBSTR) analyses. This command is also valid in PREP7. """ command = f"TIME,{time}" return self.run(command, **kwargs) - def tref(self, tref="", **kwargs): - """Defines the reference temperature for the thermal strain calculations. + def tref(self, tref: str = "", **kwargs): + r"""Defines the reference temperature for thermal strain calculations. - APDL Command: TREF + Mechanical APDL Command: `TREF `_ Parameters ---------- - tref + tref : str Reference temperature for thermal expansion. + If the uniform temperature ( :ref:`tunif` ) is not specified, it is also set to this value. + Notes ----- - Defines the reference temperature for the thermal strain calculations - in structural analyses and explicit dynamic analyses. Thermal strains - are given by : ``α * (T-TREF)``, where α is the coefficient of thermal - expansion (for more on this see the Mechanical APDL Theory Reference). - Input the strain via ALPX, ALPY, ALPZ (the secant or mean coefficient - value), or CTEX, CTEY, CTEZ (the instantaneous coefficient value), or - the thermal strain value (THSX, THSY, THSZ). T is the element - temperature. If α is temperature-dependent, TREF should be in the range - of temperatures you define using the MPTEMP command. - - Reference temperatures may also be input per material by specifying a - value on the MP material property command: - - MP,REFT,MAT,C0. - - Only a constant (non-temperature-dependent) value is valid. The value - input on the TREF command applies to all materials not having a - specified material property definition. - - To convert temperature-dependent secant coefficients of thermal - expansion (SCTE) data (properties ALPX, ALPY, ALPZ) from the definition - temperature to the reference temperature defined via a TREF (or - MP,REFT) command, issue the MPAMOD command. + + .. _TREF_notes: + + Defines the reference temperature for the thermal strain calculations in structural analyses. + Thermal strains are given by α * (T - TREF), where α is the coefficient of thermal expansion. Input + the strain via ALPX, ALPY, ALPZ (the secant or mean + coefficient value), or CTEX, CTEY, CTEZ (the instantaneous coefficient value), or the thermal strain + value (THSX, THSY, THSZ). T is the element temperature. If α is temperature-dependent, ``TREF`` + should be in the range of temperatures you define using the :ref:`mptemp` command. + + Reference temperatures may also be input per material by specifying a value on the :ref:`mp` + material property command: + + :ref:`mp`,REFT, ``MAT``, ``C0``. + + Only a constant (non-temperature-dependent) value is valid. The value input on the :ref:`tref` + command applies to all materials not having a specified material property definition. + + To convert temperature-dependent secant coefficients of thermal expansion (SCTE) data (properties + ALPX, ALPY, ALPZ) from the definition temperature to the reference temperature defined via a + :ref:`tref` (or :ref:`mp`,REFT) command, issue the :ref:`mpamod` command. This command is also valid in PREP7. """ command = f"TREF,{tref}" return self.run(command, **kwargs) - def tsres(self, array="", **kwargs): - """Defines an array of key times at which the time-stepping strategy + def tsres(self, array: str = "", **kwargs): + r"""Defines an array of key times at which the time-stepping strategy changes. - APDL Command: TSRES - changes. + Mechanical APDL Command: `TSRES `_ Parameters ---------- - array - Identifies an Nx1x1 array parameter containing the key times at - which the heat transfer time-stepping strategy changes (the time - step is reset to the initial time step based on DELTIM or NSUBST - settings). The array name must be enclosed by % signs (e.g., - %array%). See ``*DIM`` for more information on array parameters. + array : str + Identifies an ``N`` x1x1 array parameter containing the key times at which the heat transfer + time- stepping strategy changes (the time step is reset to the initial time step based on + :ref:`deltim` or :ref:`nsubst` settings). The array name must be enclosed by % signs (for + example, ``array``). See :ref:`dim` for more information on array parameters. Notes ----- - Time values in the array parameter must be in ascending order and must - not exceed the time at the end of the load step as defined on the TIME - command. The time increment between time points in the array list must - be larger than the initial time step defined on the DELTIM or NSUBST - command. Time values must also fall between the beginning and ending - time values of the load step. For multiple load step problems, you - must either change the parameter values to fall between the beginning - and ending time values of the load step or reissue the command with a - new array parameter. To clear the array parameter specification, issue - TSRES,ERASE. Results can be output at the requested time points if the - array or time values in the array are also specified in the OUTRES - command using FREQ=%array%. Use this command to reset the time- - stepping strategy within a load step. You may need to reset the time- - stepping strategy when using tabular time-varying boundary conditions. - - See Steady-State Thermal Analysis of the Thermal Analysis Guide for - more information on applying boundary conditions via tabular input. - See Transient Thermal Analysis of the Thermal Analysis Guide for more + + .. _TSRES_notes: + + Time values in the array parameter must be in ascending order and must not exceed the time at the + end of the load step as defined on the :ref:`time` command. The time increment between time points + in the array list must be larger than the initial time step defined on the :ref:`deltim` or + :ref:`nsubst` command. Time values must also fall between the beginning and ending time values of + the load step. For multiple load step problems, you must either change the parameter values to fall + between the beginning and ending time values of the load step or reissue the command with a new + array parameter. To clear the array parameter specification, issue :ref:`tsres`,ERASE. Results can + be output at the requested time points if the array or time values in the array are also specified + in the :ref:`outres` command using ``FREQ`` =``array``. Use this command to reset the time-stepping + strategy within a load step. You may need to reset the time-stepping strategy when using tabular + time-varying boundary conditions. + + See `Steady-State Thermal Analysis + `_ of the + `Thermal Analysis Guide + `_ for more + information on applying boundary conditions via tabular input. See `Transient + Thermal Analysis + `_ of + the `Thermal Analysis Guide + `_ for more information on defining the key time array. """ command = f"TSRES,{array}" return self.run(command, **kwargs) - def upcoord(self, factor="", key="", **kwargs): - """Modifies the coordinates of the active set of nodes, based on the + def upcoord(self, factor: str = "", key: str = "", **kwargs): + r"""Modifies the coordinates of the active set of nodes, based on the current displacements. - APDL Command: UPCOORD - current displacements. + Mechanical APDL Command: `UPCOORD `_ Parameters ---------- - factor - Scale factor for displacements being added to nodal coordinates. - If FACTOR = 1.0, the full displacement value will be added to each - node, 0.5, half the displacement value will be added, etc. If - FACTOR = -1, the full displacement value will be subtracted from - each node, etc. - - key + factor : str + Scale factor for displacements being added to nodal coordinates. If ``FACTOR`` = 1.0, the full + displacement value will be added to each node, 0.5, half the displacement value will be added, + etc. If ``FACTOR`` = -1, the full displacement value will be subtracted from each node, etc. + + key : str Key for zeroing displacements in the database: - OFF - Do not zero the displacements (default). + * ``OFF`` - Do not zero the displacements (default). - ON - Zero the displacements. + * ``ON`` - Zero the displacements. Notes ----- - The UPCOORD command uses displacements stored in the ANSYS database, - and not those contained within the results file, Jobname.RST. Nodal - coordinates are updated each time the command is issued. After - updating, both the nodal displacements and rotations are set to zero if - Key = ON. - - For structural solutions with an updated mesh, unless the coefficient - matrix is otherwise reformed (e.g., a new analysis or NLGEOM,ON) it - should first be reformed by issuing a KUSE,-1 command. - - UPCOORD should not be issued between load steps in structural analysis. - - For a multiphysics simulation where a CFD or electromagnetic field is - being coupled to a structure undergoing large displacements, all (or a - portion) of the surrounding field mesh may take part in the structural - solution to "move" with the displacing structure. You can use the - UPCOORD command with a suitable FACTOR to update the coordinates of the - nodes using the newly computed displacements. The mesh will now - conform with the displaced structure for subsequent field solutions. - However, the mesh should always be restored to its original location by - using an UPCOORD,FACTOR command before performing any subsequent - structural solutions. This is true for both repeated linear solutions, - and for nonlinear restarts. (All saved displacements are relative to - the original mesh location.) - - This command is not intended to replace either the large displacement - or birth and death logic. + + .. _UPCOORD_notes: + + The :ref:`upcoord` command uses displacements stored in the Mechanical APDL database, and not those + contained within the results file, :file:`Jobname.RST`. Nodal coordinates are updated each time the + command is issued. After updating, both the nodal displacements and rotations are set to zero if + ``Key`` = ON. + + For structural solutions with an updated mesh, unless the coefficient matrix is otherwise reformed + (for example, a new analysis or :ref:`nlgeom`,ON) it should first be reformed by issuing a + :ref:`kuse`,-1 command. + + :ref:`upcoord` should not be issued between load steps in structural analysis. + + For a multiphysics simulation where a CFD or electromagnetic field is being coupled to a structure + undergoing large displacements, all (or a portion) of the surrounding field mesh may take part in + the structural solution to "move" with the displacing structure. You can use the :ref:`upcoord` + command with a suitable ``FACTOR`` to update the coordinates of the nodes using the newly computed + displacements. The mesh will now conform with the displaced structure for subsequent field + solutions. However, the mesh should always be restored to its original location by using an + :ref:`upcoord`, ``FACTOR`` command before performing any subsequent structural solutions. This is + true for both repeated linear solutions, and for nonlinear restarts. (All saved displacements are + relative to the original mesh location.) + + .. warning:: + + Orientation nodes for beams and pipes always have zero displacements. Therefore, although this + command may alter the locations of other beam and pipe nodes, it has no effect on orientation + nodes. Carefully inspect the element coordinate systems on the updated model. + + This command is not intended to replace either the large-displacement or birth-and-death capability. This command is also valid in PREP7. """ @@ -775,145 +852,491 @@ def upcoord(self, factor="", key="", **kwargs): def usrcal( self, - rnam1="", - rnam2="", - rnam3="", - rnam4="", - rnam5="", - rnam6="", - rnam7="", - rnam8="", - rnam9="", + rnam1: str = "", + rnam2: str = "", + rnam3: str = "", + rnam4: str = "", + rnam5: str = "", + rnam6: str = "", + rnam7: str = "", + rnam8: str = "", + rnam9: str = "", **kwargs, ): - """Allows user-solution subroutines to be activated or deactivated. + r"""Allows user-solution subroutines to be activated or deactivated. - APDL Command: USRCAL + Mechanical APDL Command: `USRCAL `_ Parameters ---------- - rnam1, rnam2, rnam3, . . . , rnam9 - User-defined solution subroutine names to be activated. Up to nine - may be defined on one command or multiple commands may be used. If - Rnam1 = ALL, activate all valid user subroutines. If Rnam1 = - NONE, deactivate all valid user subroutines. All characters are - required: + rnam1 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam2 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam3 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. - USREFL - Allows user defined scalar field (body force) loads. + * ``USOLBEG`` - Allows user access before each solution. - USERCV - Allows user defined convection (surface) loads. + * ``ULDBEG`` - Allows user access before each load step. - USERPR - Allows user defined pressure (surface) loads. + * ``USSBEG`` - Allows user access before each substep. - USERFX - Allows user-defined heat flux (surface) loads. + * ``UITBEG`` - Allows user access before each equilibrium iteration. - USERCH - Allows user-defined charge density (surface) loads. + * ``UITFIN`` - Allows user access after each equilibrium iteration. - USERFD - Computes the complex load vector for the frequency domain logic. + * ``USSFIN`` - Allows user access after each substep. - USEROU - Allows user supplied element output. + * ``ULDFIN`` - Allows user access after each load step. - USERMC - Allows user control of the hygrothermal growth). + * ``USOLFIN`` - Allows user access after each solution. - USOLBEG - Allows user access before each solution. + * ``UANFIN`` - Allows user access at end of run. - ULDBEG - Allows user access before each load step. + * ``UELMATX`` - Allows user access to element matrices and load vectors. - USSBEG - Allows user access before each substep. + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. - UITBEG - Allows user access before each equilibrium iteration. + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. - UITFIN - Allows user access after each equilibrium iteration. + rnam4 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: - USSFIN - Allows user access after each substep. + * ``USREFL`` - Allows user defined scalar field (body force) loads. - ULDFIN - Allows user access after each load step. + * ``USERCV`` - Allows user defined convection (surface) loads. - USOLFIN - Allows user access after each solution. + * ``USERPR`` - Allows user defined pressure (surface) loads. - UANBEG - Allows user access at start of run. + * ``USERFX`` - Allows user-defined heat flux (surface) loads. - UANFIN - Allows user access at end of run. + * ``USERCH`` - Allows user-defined charge density (surface) loads. - UELMATX - Allows user access to element matrices and load vectors. + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. - UTIMEINC - Allows a user-defined time step, overriding the program-determined time step. + * ``USEROU`` - Allows user supplied element output. - UCNVRG - Allows user-defined convergence checking, overriding the program-determined - convergence. + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam5 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam6 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam7 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam8 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. + + rnam9 : str + User-defined solution subroutine names to be activated. Up to nine may be defined on one command or + multiple commands may be used. If ``Rnam1`` = ALL, activate all valid user subroutines. If ``Rnam1`` = NONE, deactivate all valid user subroutines. All characters are required: + + * ``USREFL`` - Allows user defined scalar field (body force) loads. + + * ``USERCV`` - Allows user defined convection (surface) loads. + + * ``USERPR`` - Allows user defined pressure (surface) loads. + + * ``USERFX`` - Allows user-defined heat flux (surface) loads. + + * ``USERCH`` - Allows user-defined charge density (surface) loads. + + * ``USERFD`` - Computes the complex load vector for the frequency domain logic. + + * ``USEROU`` - Allows user supplied element output. + + * ``USOLBEG`` - Allows user access before each solution. + + * ``ULDBEG`` - Allows user access before each load step. + + * ``USSBEG`` - Allows user access before each substep. + + * ``UITBEG`` - Allows user access before each equilibrium iteration. + + * ``UITFIN`` - Allows user access after each equilibrium iteration. + + * ``USSFIN`` - Allows user access after each substep. + + * ``ULDFIN`` - Allows user access after each load step. + + * ``USOLFIN`` - Allows user access after each solution. + + * ``UANFIN`` - Allows user access at end of run. + + * ``UELMATX`` - Allows user access to element matrices and load vectors. + + * ``UTIMEINC`` - Allows a user-defined time step, overriding the program-determined time step. + + * ``UCNVRG`` - Allows user-defined convergence checking, overriding the program-determined + convergence. Notes ----- - Allows certain user-solution subroutines to be activated or deactivated - (system-dependent). This command only affects the subroutines named. - Other user subroutines (such as user elements, user creep, etc.) have - their own activation controls described with the feature. - - The routines are commented and should be listed after performing a - custom installation from the distribution media for more details. See - also the Advanced Analysis Guide for a general description of user- + + .. _USRCAL_notes: + + Allows certain user-solution subroutines to be activated or deactivated (system-dependent). This + command only affects the subroutines named. Other user subroutines (such as user elements, user + creep, etc.) have their own activation controls described with the feature. + + The UAnBeg subroutine that allows user access at the start of a run does not require activation by + this command; it is automatically activated when the program is started. + + The routines are commented and should be listed after performing a custom installation from the + distribution media for more details. See also the `Advanced Analysis Guide + `_ for a + general description of user- programmable features. - Users must have system permission, system access, and knowledge to - write, compile, and link the appropriate subroutines into the program - at the site where it is to be run. All routines should be written in - FORTRAN. (For more information on FORTRAN compilers please refer to - either the ANSYS, Inc. Windows Installation Guide or the ANSYS, Inc. - Linux Installation Guide for details specific to your platform or - operating system.) Issue USRCAL,STAT to list the status of these user - subroutines. Since a user-programmed subroutine is a nonstandard use - of the program, the verification of any ANSYS run incorporating these - commands is entirely up to the user. In any contact with ANSYS - customer support regarding the performance of a custom version of the - ANSYS program, you should explicitly state that a user programmable - feature has been used. + You must have system permission, system access, and knowledge to write, compile, and link the + appropriate subroutines into the program at your site. - This command is also valid in PREP7. + All routines should be written in FORTRAN. (For more information about FORTRAN compilers, refer to + either the `Ansys, Inc. Windows Installation Guide + `_ or + the `Ansys, Inc. Linux Installation Guide + `_ for + details specific to your platform or operating system.) + + Issue :ref:`usrcal`,STAT to list the status of these user subroutines. - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. + Because a user-programmed subroutine is a nonstandard use of the program, the verification of any + Mechanical APDL run incorporating these commands is entirely your responsibility. In any contact + with + customer support regarding the performance of a custom version of Mechanical APDL, explicitly state + that a + user-programmable feature has been used. + + This command is also valid in PREP7. """ command = f"USRCAL,{rnam1},{rnam2},{rnam3},{rnam4},{rnam5},{rnam6},{rnam7},{rnam8},{rnam9}" return self.run(command, **kwargs) - def wrfull(self, ldstep="", **kwargs): - """Stops solution after assembling global matrices. + def wrfull(self, ldstep: str = "", **kwargs): + r"""Stops solution after assembling global matrices. - APDL Command: WRFULL + Mechanical APDL Command: `WRFULL `_ Parameters ---------- - ldstep + ldstep : str Specify action to take: - OFF or 0 - Turn off feature (default) + * ``OFF or 0`` - Turn off feature (default) - N - Turn on feature and set it to stop after assembling the global matrices and - writing the .FULL file for load step N. + * ``N`` - Turn on feature and set it to stop after assembling the global matrices and writing the + :file:`.FULL` file for load step N. Notes ----- - This command is used in conjunction with the SOLVE command to generate - the assembled matrix file (.FULL file) only. The element matrices are - assembled into the relevant global matrices for the particular analysis - being performed and the .FULL file is written. Equation solution and - the output of data to the results file are skipped. To dump the - matrices written on the .FULL file into Harwell-Boeing format, use the - HBMAT command in /AUX2. To copy the matrices to a postscript format - that can be viewed graphically, use the PSMAT command. - - To use the LSSOLVE macro with this command, you may need to modify the - LSSOLVE macro to properly stop at the load step of interest. - - This command only valid for linear static, full harmonic, and full - transient analyses when the sparse direct solver is selected. This - command is also valid for buckling or modal analyses with any mode - extraction method. This command is not valid for nonlinear analyses. - It is not supported in a linear perturbation analysis. - - In general, the assembled matrix file .FULL contains stiffness, mass, - and damping matrices. However, the availability of the matrices depends - on the analysis type chosen when the file is written. + + .. _WRFULL_notes: + + This command is used in conjunction with the :ref:`solve` command to generate the assembled matrix + file ( :file:`.FULL` file) only. The element matrices are assembled into the relevant global + matrices for the particular analysis being performed and the :file:`.FULL` file is written. Equation + solution and the output of data to the results file are skipped. To dump the matrices written on the + :file:`.FULL` file into Harwell-Boeing format, use the :ref:`hbmat` command in /AUX2. To copy the + matrices to a postscript format that can be viewed graphically, use the :ref:`psmat` command. + + To use the :ref:`lssolve` macro with this command, you may need to modify the :ref:`lssolve` macro + to properly stop at the load step of interest. + + This command only valid for linear static, full harmonic, and full transient analyses when the + sparse direct solver is selected. This command is also valid for buckling or modal analyses with any + mode extraction method. This command is not valid for nonlinear analyses. It is not supported in a + linear perturbation analysis. + + In general, the assembled matrix file :file:`.FULL` contains stiffness, mass, and damping matrices. + However, the availability of the matrices depends on the analysis type chosen when the file is + written. Some analyses do not write the matrices individually but instead write combined matrices. + For example, a full transient writes a combined stiffness/mass/damping matrix to the full file. """ command = f"WRFULL,{ldstep}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/master_dof.py b/src/ansys/mapdl/core/_commands/solution/master_dof.py index 451bad85394..e5a065fdf0c 100644 --- a/src/ansys/mapdl/core/_commands/solution/master_dof.py +++ b/src/ansys/mapdl/core/_commands/solution/master_dof.py @@ -21,176 +21,306 @@ # SOFTWARE. -class MasterDOF: +class MasterDof: + def m( self, - node="", - lab1="", - nend="", - ninc="", - lab2="", - lab3="", - lab4="", - lab5="", - lab6="", + node: str = "", + lab1: str = "", + nend: str = "", + ninc: str = "", + lab2: str = "", + lab3: str = "", + lab4: str = "", + lab5: str = "", + lab6: str = "", + support: str = "", **kwargs, ): - """Defines master degrees of freedom for superelement generation analyses. + r"""Defines master degrees of freedom (MDOFs) for superelement generation analyses. - APDL Command: M + Mechanical APDL Command: `M `_ Parameters ---------- - node - Node number at which master degree of freedom is defined. If ALL, - define master degrees of freedom at all selected nodes (NSEL). If - NODE = P, graphical picking is enabled and all remaining command - fields are ignored (valid only in the GUI). A component name may - also be substituted for NODE. - - lab1 - Valid degree of freedom label. If ALL, use all appropriate labels. - Structural labels: UX, UY, or UZ (displacements); ROTX, ROTY, or - ROTZ (rotations). Thermal labels: TEMP, TBOT, TE2, TE3, . . ., TTOP - (temperature). Electric labels: VOLT (voltage). - - nend, ninc - Define all nodes from NODE to NEND (defaults to NODE) in steps of - NINC (defaults to 1) as master degrees of freedom in the specified - direction. - - lab2, lab3, lab4, . . . , lab6 - Additional master degree of freedom labels. The nodes defined are - associated with each label specified. + node : str + Node number at which an MDOF is defined. If ALL, define MDOFs at all selected nodes ( + :ref:`nsel` ). If ``NODE`` = P, graphical picking is enabled and all remaining command fields + are ignored (valid only in the GUI). A component name may also be substituted for ``NODE``. + + lab1 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + nend : str + Define all nodes from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` + (defaults to 1) as MDOFs in the specified direction. + + ninc : str + Define all nodes from ``NODE`` to ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` + (defaults to 1) as MDOFs in the specified direction. + + lab2 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + lab3 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + lab4 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + lab5 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + lab6 : str + Additional MDOF labels. The nodes defined are associated with each label specified. + + support : str + Pseudo-constraints key for the free-interface ( :ref:`cmsopt`,FREE) and residual-flexible free- + interface ( :ref:`cmsopt`, RFFB) CMS method analyses: + + OFF - Defined MDOFs remain free during the mode-extraction analysis (default). + + ON - Defined MDOFs are constrained during the mode-extraction analysis. Notes ----- - Defines master degrees of freedom (MDOF) for superelement generation. - If defined for other analyses, MDOF are ignored. If used in SOLUTION, - this command is valid only within the first load step. - Repeat M command for additional master degrees of freedom. The limit - for the number of master nodes used is determined by the maximum system - memory available. - - The substructure (ANTYPE,SUBSTR) analysis utilizes the matrix - condensation technique to reduce the structure matrices to those - characterized by a set of master degrees of freedom. - - Master degrees of freedom are identified by a list of nodes and their - nodal directions. The actual degree of freedom directions available - for a particular node depends upon the degrees of freedom associated - with element types (ET) at that node. There must be some mass (or - stress stiffening in the case of the buckling analysis) associated with - each master degree of freedom (except for the VOLT label). The mass - may be due either to the distributed mass of the element or due to - discrete lumped masses at the node. If a master degree of freedom is - specified at a constrained point, it is ignored. If a master degree of - freedom is specified at a coupled node, it should be specified at the - prime node of the coupled set. - - Substructure analysis connection points must be defined as master - degrees of freedom. + .. _M_notes: + + Defines master degrees of freedom (MDOFs) for superelement generation. If defined for other + analyses, MDOFs are ignored. If used in the SOLUTION processor, this command is valid only within + the first load step. + + Reissue :ref:`m` for additional MDOFs. The number of master nodes allowed is limited only by the + maximum system memory available. + + The substructure ( :ref:`antype`,SUBSTR) analysis uses the matrix condensation technique to reduce + the structure matrices to those characterized by a set of MDOFs. + + MDOFs are identified by a list of nodes and their nodal directions. The actual degree-of-freedom + directions available for a given node depends upon the degrees of freedom associated with element + types ( :ref:`et` ) at that node. + + There must be some mass (or stress stiffening in the case of a buckling analysis) associated with + each MDOF (except for the VOLT label). The mass may be due either to the distributed mass of the + element or due to discrete lumped masses at the node. + + If an MDOF is specified at a constrained point, it is ignored. + + If an MDOF is specified at a coupled node, it should be specified at the prime node of the coupled + set. + + For cyclic symmetry superelements, if MDOFs are defined at both low- and high-edge nodes, the cyclic + constraint equations between those nodes are ignored. + + Substructure analysis connection points must be defined as MDOFs. + + The ``SUPPORT`` argument is ignored for the fixed-interface CMS method analysis ( + :ref:`cmsopt`,FIX). This command is also valid in PREP7. """ - command = f"M,{node},{lab1},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6}" + command = f"M,{node},{lab1},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6},{support}" return self.run(command, **kwargs) def mdele( self, - node="", - lab1="", - nend="", - ninc="", - lab2="", - lab3="", - lab4="", - lab5="", - lab6="", + node: str = "", + lab1: str = "", + nend: str = "", + ninc: str = "", + lab2: str = "", + lab3: str = "", + lab4: str = "", + lab5: str = "", + lab6: str = "", + support: str = "", **kwargs, ): - """Deletes master degrees of freedom. + r"""Deletes master degrees of freedom. - APDL Command: MDELE + Mechanical APDL Command: `MDELE `_ Parameters ---------- - node, lab1, nend, ninc - Delete master degrees of freedom in the Lab1 direction [M] from - NODE to NEND (defaults to NODE) in steps of NINC (defaults to 1). - If NODE = ALL, NEND and NINC are ignored and masters for all - selected nodes [NSEL] are deleted. If Lab1 = ALL, all label - directions will be deleted. If NODE = P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). A component name may also be substituted for NODE. - - lab2, lab3, lab4, . . . , lab6 + node : str + Delete master degrees of freedom in the ``Lab1`` direction ( :ref:`m` ) from ``NODE`` to + ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` (defaults to 1). If ``NODE`` = ALL, + ``NEND`` and ``NINC`` are ignored and masters for all selected nodes ( :ref:`nsel` ) are + deleted. If ``Lab1`` = ALL, all label directions will be deleted. If ``NODE`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``NODE``. + + lab1 : str + Delete masters in these additional directions. + + nend : str + Delete master degrees of freedom in the ``Lab1`` direction ( :ref:`m` ) from ``NODE`` to + ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` (defaults to 1). If ``NODE`` = ALL, + ``NEND`` and ``NINC`` are ignored and masters for all selected nodes ( :ref:`nsel` ) are + deleted. If ``Lab1`` = ALL, all label directions will be deleted. If ``NODE`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``NODE``. + + ninc : str + Delete master degrees of freedom in the ``Lab1`` direction ( :ref:`m` ) from ``NODE`` to + ``NEND`` (defaults to ``NODE`` ) in steps of ``NINC`` (defaults to 1). If ``NODE`` = ALL, + ``NEND`` and ``NINC`` are ignored and masters for all selected nodes ( :ref:`nsel` ) are + deleted. If ``Lab1`` = ALL, all label directions will be deleted. If ``NODE`` = P, graphical + picking is enabled and all remaining command fields are ignored (valid only in the GUI). A + component name may also be substituted for ``NODE``. + + lab2 : str + Delete masters in these additional directions. + + lab3 : str Delete masters in these additional directions. + lab4 : str + Delete masters in these additional directions. + + lab5 : str + Delete masters in these additional directions. + + lab6 : str + Delete masters in these additional directions. + + support : str + Pseudo-constraints key for the free-interface ( :ref:`cmsopt`,FREE) and residual-flexible free- + interface ( :ref:`cmsopt`,RFFB) CMS method analyses: + + OFF - delete selected master degrees of freedom and any pseudo-constraints applied on them with + SUPPORT = ON in the :ref:`m` command (default). + + ON - only delete any pseudo-constraints applied on selected master degrees of freedom. + Notes ----- - Deletes master degrees of freedom. If used in SOLUTION, this command - is valid only within the first load step. + + .. _MDELE_notes: + + Deletes master degrees of freedom. If used in SOLUTION, this command is valid only within the first + load step. + + The ``SUPPORT`` argument is ignored for the fixed-interface CMS method analysis ( + :ref:`cmsopt`,FIX). This command is also valid in PREP7. """ - command = ( - f"MDELE,{node},{lab1},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6}" - ) + command = f"MDELE,{node},{lab1},{nend},{ninc},{lab2},{lab3},{lab4},{lab5},{lab6},{support}" return self.run(command, **kwargs) - def mgen(self, itime="", inc="", node1="", node2="", ninc="", **kwargs): - """Generates additional MDOF from a previously defined set. + def mgen( + self, + itime: str = "", + inc: str = "", + node1: str = "", + node2: str = "", + ninc: str = "", + **kwargs, + ): + r"""Generates additional MDOF from a previously defined set. - APDL Command: MGEN + Mechanical APDL Command: `MGEN `_ Parameters ---------- - itime, inc - Do this generation operation a total of ITIMEs, incrementing all - nodes in the set by INC each time after the first. ITIME must be > - 1 for generation to occur. All previously defined master degree of - freedom directions are included in the set. A component name may - also be substituted for ITIME. - - node1, node2, ninc - Generate master degrees of freedom from set beginning with NODE1 to - NODE2 (defaults to NODE1) in steps of NINC (defaults to 1). If - NODE1 = ALL, NODE2 and NINC are ignored and set is all selected - nodes [NSEL]. If NODE1 = P, graphical picking is enabled and all - remaining command fields are ignored (valid only in the GUI). + itime : str + Do this generation operation a total of ``ITIME`` s, incrementing all nodes in the set by + ``INC`` each time after the first. ``ITIME`` must be > 1 for generation to occur. All previously + defined master degree of freedom directions are included in the set. A component name may also + be substituted for ``ITIME``. + + inc : str + Do this generation operation a total of ``ITIME`` s, incrementing all nodes in the set by + ``INC`` each time after the first. ``ITIME`` must be > 1 for generation to occur. All previously + defined master degree of freedom directions are included in the set. A component name may also + be substituted for ``ITIME``. + + node1 : str + Generate master degrees of freedom from set beginning with ``NODE1`` to ``NODE2`` (defaults to + ``NODE1`` ) in steps of ``NINC`` (defaults to 1). If ``NODE1`` = ALL, ``NODE2`` and ``NINC`` are + ignored and set is all selected nodes ( :ref:`nsel` ). If ``NODE1`` = P, graphical picking is + enabled and all remaining command fields are ignored (valid only in the GUI). + + node2 : str + Generate master degrees of freedom from set beginning with ``NODE1`` to ``NODE2`` (defaults to + ``NODE1`` ) in steps of ``NINC`` (defaults to 1). If ``NODE1`` = ALL, ``NODE2`` and ``NINC`` are + ignored and set is all selected nodes ( :ref:`nsel` ). If ``NODE1`` = P, graphical picking is + enabled and all remaining command fields are ignored (valid only in the GUI). + + ninc : str + Generate master degrees of freedom from set beginning with ``NODE1`` to ``NODE2`` (defaults to + ``NODE1`` ) in steps of ``NINC`` (defaults to 1). If ``NODE1`` = ALL, ``NODE2`` and ``NINC`` are + ignored and set is all selected nodes ( :ref:`nsel` ). If ``NODE1`` = P, graphical picking is + enabled and all remaining command fields are ignored (valid only in the GUI). Notes ----- - Generates additional master degrees of freedom from a previously - defined set. If used in SOLUTION, this command is valid only within - the first load step. + + .. _MGEN_notes: + + Generates additional master degrees of freedom from a previously defined set. If used in SOLUTION, + this command is valid only within the first load step. + + For the free-interface ( :ref:`cmsopt`, FREE) and residual-flexible free-interface ( :ref:`cmsopt`, + RFFB) CMS method analyses, pseudo-constraints could have been applied on some master degrees of + freedom of the previously defined set (SUPPORT = ON in the :ref:`m` command). The master degrees of + freedom generated from these with the :ref:`mgen` command are also defined with pseudo-constraints. This command is also valid in PREP7. """ command = f"MGEN,{itime},{inc},{node1},{node2},{ninc}" return self.run(command, **kwargs) - def mlist(self, node1="", node2="", ninc="", **kwargs): - """Lists the MDOF of freedom. + def mlist(self, node1: str = "", node2: str = "", ninc: str = "", **kwargs): + r"""Lists the MDOF of freedom. - APDL Command: MLIST + Mechanical APDL Command: `MLIST `_ Parameters ---------- - node1, node2, ninc - List master degrees of freedom from NODE1 to NODE2 (defaults - toNODE1) in steps of NINC (defaults to 1). If NODE1 = ALL - (default), NODE2 and NINC are ignored and masters for all selected - nodes [NSEL] are listed. If NODE1 = 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 NODE1 - (NODE2 and NINC are ignored). + node1 : str + List master degrees of freedom from ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + masters for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + node2 : str + List master degrees of freedom from ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + masters for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + ninc : str + List master degrees of freedom from ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + masters for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = 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 ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). Notes ----- + + .. _MLIST_notes: + Lists the master degrees of freedom. + + For the free-interface CMS method analysis ( :ref:`cmsopt`,FREE), any pseudo-constraints applied on + master degrees of freedom with ``SUPPORT`` = ON in the :ref:`m` command will be listed when + :ref:`mlist` is issued after :ref:`cmsopt` (see example printout below). + + .. code:: apdl + + NODE LABEL SUPPORT + 8529 UX + 8529 UY + 8529 UZ + 8545 UX ON + 8545 UY ON + 8545 UZ ON """ command = f"MLIST,{node1},{node2},{ninc}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/misc_loads.py b/src/ansys/mapdl/core/_commands/solution/misc_loads.py new file mode 100644 index 00000000000..b25a8a2f942 --- /dev/null +++ b/src/ansys/mapdl/core/_commands/solution/misc_loads.py @@ -0,0 +1,2471 @@ +# 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 MiscLoads: + + def anpres( + self, + nfram: str = "", + delay: str = "", + ncycl: str = "", + refframe: int | str = "", + **kwargs, + ): + r"""Produces an animated sequence of the time-harmonic pressure variation of an engine-order excitation + in a cyclic harmonic analysis. + + Mechanical APDL Command: `ANPRES `_ + + Parameters + ---------- + nfram : str + Number of frame captures per cycle. Defaults to 3 times the number of sectors. + + delay : str + Time delay (seconds) during animation. Defaults to 0.1 seconds. + + ncycl : str + Number of animation cycles. Defaults to 5. + + refframe : int or str + Reference frame for the model rotation. + + * ``0`` - Rotating reference frame (default). The model remains fixed in space and the pressure + revolve around the model. + + * ``1`` - Stationary reference frame. The model rotates and the pressure locations remain fixed in + space. + + Notes + ----- + + .. _ANPRES_notes: + + :ref:`anpres` invokes a macro which produces an animated sequence of the time-harmonic applied + pressure in the case of a mode-superposition harmonic analysis ( :ref:`antype`,HARMIC with + :ref:`cycopt`,MSUP,ON). The engine-order excitation must also have been specified ( + :ref:`cycfreq`,EO). While pressure loads are not accepted as valid loading in a mode-superposition + analysis (they must be applied in the modal analysis and the modal load vector applied in the mode- + superposition analysis) you can apply them for the purposes of this animation. + + For ``RefFrame`` = 1 (stationary reference frame), the rotational velocity from the Linear + Perturbation step, or the current :ref:`omega` or :ref:`cgomga` value, is used to determine the + rotation direction about the cyclic cylindrical axis, otherwise a positive rotation is assumed. + + You may use :ref:`hbc`,,ON to hide overlapping pressure faces, and use :ref:`gline`,,-1 to suppress + the element outlines if desired. + """ + command = f"ANPRES,{nfram},{delay},{ncycl},{refframe}" + return self.run(command, **kwargs) + + def aport( + self, + portnum: str = "", + label: str = "", + kcn: str = "", + pres: str = "", + phase: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + **kwargs, + ): + r"""Specifies input data for plane wave and acoustic duct ports. + + Mechanical APDL Command: `APORT `_ + + Parameters + ---------- + portnum : str + Port number. This number is associated with an exterior port or interior port previously + specified by the :ref:`sf` and :ref:`bf` family of commands, respectively. The number must be + between 1 and 50. + + label : str + * ``PLAN`` - Incident plane wave. + + * ``RECT`` - Rectangular duct. + + * ``CIRC`` - Circular duct. + + * ``COAX`` - Coaxial duct. + + * ``LIST`` - List the port settings. If ``PortNum`` = ALL, list the port settings for all defined + ports. + + * ``DELE`` - Delete defined ports. If ``PortNum`` = ALL, delete all defined ports. + + kcn : str + A previously-defined local ( ``KCN`` >10) or global ( ``KCN`` = 0) Cartesian coordinate system + number used to specify the geometric properties of the duct. Defaults to the global Cartesian + coordinate system (0). The local Z-direction must be the direction of wave propagation. The + origin of the local coordinate system must be centered about the face of the duct port without + considering symmetry. + + pres : str + Zero-to-peak amplitude of the pressure. If blank, the port will appear as a matching impedance. + + phase : str + Phase angle of the applied pressure in degrees. Defaults to 0. + + val1 : str + Additional input. The meaning of ``VAL1`` through ``VAL4`` varies depending on the specified + ``Label``. + + ``Label`` = PLAN: + + * ``VAL1`` - :math:`equation not available` angle from positive X-axis to positive Y-axis in the + local Cartesian coordinates ( ``KCN`` ). + + * ``VAL2`` - :math:`equation not available` angle away from positive Z-axis in the local Cartesian + coordinates ( ``KCN`` ). + + * ``VAL3-VAL4`` - Not used. + + ``Label`` = RECT: + + * ``VAL1`` - Width of the rectangular duct. + + * ``VAL2`` - Height of the rectangular duct. + + * ``VAL3`` - Mode index for pressure variation along the width (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the height (defaults to 0). + + ``Label`` = CIRC: + + * ``VAL1`` - Radius of the circular duct. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + ``Label`` = COAX: + + * ``VAL1`` - Inner radius of the coaxial duct. + + * ``VAL2`` - Outer radius of the coaxial duct. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + val2 : str + Additional input. The meaning of ``VAL1`` through ``VAL4`` varies depending on the specified + ``Label``. + + ``Label`` = PLAN: + + * ``VAL1`` - :math:`equation not available` angle from positive X-axis to positive Y-axis in the + local Cartesian coordinates ( ``KCN`` ). + + * ``VAL2`` - :math:`equation not available` angle away from positive Z-axis in the local Cartesian + coordinates ( ``KCN`` ). + + * ``VAL3-VAL4`` - Not used. + + ``Label`` = RECT: + + * ``VAL1`` - Width of the rectangular duct. + + * ``VAL2`` - Height of the rectangular duct. + + * ``VAL3`` - Mode index for pressure variation along the width (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the height (defaults to 0). + + ``Label`` = CIRC: + + * ``VAL1`` - Radius of the circular duct. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + ``Label`` = COAX: + + * ``VAL1`` - Inner radius of the coaxial duct. + + * ``VAL2`` - Outer radius of the coaxial duct. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + val3 : str + Additional input. The meaning of ``VAL1`` through ``VAL4`` varies depending on the specified + ``Label``. + + ``Label`` = PLAN: + + * ``VAL1`` - :math:`equation not available` angle from positive X-axis to positive Y-axis in the + local Cartesian coordinates ( ``KCN`` ). + + * ``VAL2`` - :math:`equation not available` angle away from positive Z-axis in the local Cartesian + coordinates ( ``KCN`` ). + + * ``VAL3-VAL4`` - Not used. + + ``Label`` = RECT: + + * ``VAL1`` - Width of the rectangular duct. + + * ``VAL2`` - Height of the rectangular duct. + + * ``VAL3`` - Mode index for pressure variation along the width (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the height (defaults to 0). + + ``Label`` = CIRC: + + * ``VAL1`` - Radius of the circular duct. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + ``Label`` = COAX: + + * ``VAL1`` - Inner radius of the coaxial duct. + + * ``VAL2`` - Outer radius of the coaxial duct. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + val4 : str + Additional input. The meaning of ``VAL1`` through ``VAL4`` varies depending on the specified + ``Label``. + + ``Label`` = PLAN: + + * ``VAL1`` - :math:`equation not available` angle from positive X-axis to positive Y-axis in the + local Cartesian coordinates ( ``KCN`` ). + + * ``VAL2`` - :math:`equation not available` angle away from positive Z-axis in the local Cartesian + coordinates ( ``KCN`` ). + + * ``VAL3-VAL4`` - Not used. + + ``Label`` = RECT: + + * ``VAL1`` - Width of the rectangular duct. + + * ``VAL2`` - Height of the rectangular duct. + + * ``VAL3`` - Mode index for pressure variation along the width (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the height (defaults to 0). + + ``Label`` = CIRC: + + * ``VAL1`` - Radius of the circular duct. + + * ``VAL2`` - Not used. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + ``Label`` = COAX: + + * ``VAL1`` - Inner radius of the coaxial duct. + + * ``VAL2`` - Outer radius of the coaxial duct. + + * ``VAL3`` - Mode index for pressure variation along the azimuth (defaults to 0). + + * ``VAL4`` - Mode index for pressure variation along the radii (defaults to 0). + + Notes + ----- + + .. _APORT_notes: + + Use the :ref:`aport` command to launch a specified analytic acoustic mode into a guided duct. + + The low-order ``FLUID30`` element does not support the higher modes in the coaxial duct ( ``Label`` + = COAX). + + For more information, see `Specified Mode Excitation in an Acoustic Duct + `_ + `Analytic Port Modes in a Duct + `_ + """ + command = ( + f"APORT,{portnum},{label},{kcn},{pres},{phase},,{val1},{val2},{val3},{val4}" + ) + return self.run(command, **kwargs) + + def asifile( + self, + opt: str = "", + fname: str = "", + ext: str = "", + oper: str = "", + kdim: str = "", + kout: str = "", + limit: str = "", + resopt: str = "", + **kwargs, + ): + r"""Writes or reads one-way acoustic-structural coupling data. + + Mechanical APDL Command: `ASIFILE `_ + + Parameters + ---------- + opt : str + Command behavior option: + + * ``WRITE`` - Write the structural results to the specified file. + + * ``READ`` - Read the structural results from the specified file. This option is invalid during + :ref:`post1` postprocessing. + + fname : str + File name and directory path of a one-way acoustic-structural coupling data file (248 characters + maximum, including the characters needed for the directory path). An unspecified directory path + defaults to the working directory; in this case, you can use all 248 characters for the file + name (defaults to :file:`jobname` ). + + ext : str + File name extension of the one-way acoustic-structural coupling data file (defaults to + :file:`.asi` ). + + oper : str + Command operation: + + * ``NOMAP`` - No mapping occurs between the structural and acoustic models when reading the + structural results from the specified file (default). + + * ``MAP`` - Maps the results from the structural to the acoustic model. (See :ref:`ASIFILE_notes`.) + + kdim : str + Interpolation criteria. Valid only when ``Oper`` = MAP. + + If ``kDim`` = 2 or 0, two-dimensional interpolation is applied (that is, interpolate occurs on a + surface). + + kout : str + Outside region results. Valid only when ``Oper`` = MAP. + + If ``kOut`` = 0, use the value(s) of the nearest region point for points outside of the region. + + If ``kOut`` = 1, set results extrapolated outside of the region to zero. + + limit : str + Number of nearby nodes considered for interpolation. Valid only when ``Oper`` = MAP. + + Minimum = 5. Default = 20. + + Lower values reduce processing time; however, some distorted or irregular meshes require a + higher value to encounter three nodes for triangulation. + + resopt : str + Transient results option: + + * ``ACEL`` - Output or input the particle acceleration in a transient analysis (default). + + * ``VELO`` - Output or input the particle velocity in a transient analysis. + + Notes + ----- + + .. _ASIFILE_notes: + + The :ref:`asifile` command writes to, or reads from, a file containing one-way acoustic-structural + coupling data. + + Results data on the one-way coupling interface (defined by the :ref:`sf`,,FSIN command) in the + structural model are written to the one-way coupling result data file during the structural + solution. + + By default, one-way coupling results data are read into the acoustic model as the velocity + (harmonic) or acceleration (transient) excitation during the sequential acoustic solution. If the + transient is to be solved with the velocity potential formulation in acoustics, set ``ResOpt`` = + VELO to write/read the results data as velocity excitation. + + If ``Oper`` = NOMAP, both structural and acoustic models must share the same node number on the one- + way coupling interface. + + If ``Oper`` = MAP: + + * The one-way coupling interface must be defined in the acoustic model ( :ref:`sf`,,FSIN) such that + it corresponds to the field-surface interface number (FSIN) in the structural model. + + * The output points are correct only if they are within the boundaries set via the specified input + points. + + * Calculations for out-of-bound points require much more processing time than do points that are + within bounds. + + * For each point in the acoustic destination mesh, the command searches all possible triangles in + the structural source mesh to find the best triangle containing each point, then performs a linear + interpolation inside this triangle. For faster and more accurate results, consider your + interpolation method and search criteria carefully (see ``LIMIT`` ). + + You can also write an :file:`.asi` file during postprocessing of the structural model. In the POST1 + postprocessor ( :ref:`post1` ), issue the command :ref:`asifile`,WRITE, ``Fname``, ``Ext`` to + output results on selected surface nodes of the structural model. In the subsequent acoustic + analysis, apply the :ref:`sf`,,FSIN,1 command on the selected nodes of the acoustic model, and + issue the :ref:`asifile`,READ, ``Fname``, ``Ext`` command to read the :file:`.asi` file. + + One-way coupling excitation can be applied to multiple frequencies or time steps. + """ + command = f"ASIFILE,{opt},{fname},{ext},{oper},{kdim},{kout},{limit},,{resopt}" + return self.run(command, **kwargs) + + def awave( + self, + wavenum: str = "", + wavetype: str = "", + opt1: str = "", + opt2: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + val10: str = "", + val11: str = "", + val12: str = "", + val13: str = "", + **kwargs, + ): + r"""Specifies input data for an acoustic incident wave. + + Mechanical APDL Command: `AWAVE `_ + + Parameters + ---------- + wavenum : str + Wave number. You specify the integer number for an acoustic incident wave inside or outside the + model. The number must be between 1 and 20. + + wavetype : str + Wave type: + + * ``PLAN`` - Planar incident wave + + * ``MONO`` - Monopole or pulsating sphere incident wave + + * ``DIPO`` - Dipole incident wave + + * ``BACK`` - Back enclosed loudspeaker + + * ``BARE`` - Bare loudspeaker + + * ``STATUS`` - Displays the status of the acoustic wave settings if ``Wavenum`` = a number between 1 + and 20 or ALL. + + * ``DELE`` - Deletes the acoustic wave settings if ``Wavenum`` = a number between 1 and 20 or ALL. + + opt1 : str + * ``PRES`` - Pressure + + * ``VELO`` - Velocity + + opt2 : str + * ``EXT`` - Incident wave outside the model. + + * ``INT`` - Incident wave inside the model. This option is only available for pure scattered + pressure formulation. + + For ``Wavetype`` = PLAN, only ``Opt2`` = EXT is available. + + val1 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val2 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val3 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val4 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val5 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val6 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val7 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val8 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val9 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val10 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val11 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val12 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + val13 : str + If ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL1`` - Amplitude of pressure or normal velocity to the sphere surface. + + * ``VAL2`` - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 degrees. + + If ``Wavetype`` = PLAN: + + * ``VAL3`` - Incident ϕ angle from x axis toward y axis. + + * ``VAL4`` - Incident θ angle from z axis toward y axis. + + * ``VAL5`` - Not used. + + If ``Wavetype`` = MONO, DIPO, BACK, or BARE: + + * ``VAL3 - VAL5`` - Global Cartesian coordinate values of source position. + + If + ``Wavetype`` = PLAN, MONO, DIPO, BACK, or BARE: + + * ``VAL6`` - Mass density of base medium (defaults to 1.2041 kg/m3). + + * ``VAL7`` - Speed of sound in base medium (defaults to 343.24 m/s). + + * ``VAL8`` - Radius of pulsating sphere (not used for ``Wavetype`` = PLAN). + + * ``VAL9`` - Dipole length (only available for ``Wavetype`` = DIPO, BARE). + + * ``VAL10 - VAL12`` - Unit vector of dipole axis from the positive to the negative. Only available + for ``Wavetype`` = DIPO, BARE. + + * ``VAL13`` - Port number if the incident power is required on the port + + Notes + ----- + Use the :ref:`asol` command to activate the scattered field algorithm and the :ref:`ascres` command + for output control with the scattered field algorithm. Refer to `Acoustics + `_ + + + """ + command = f"AWAVE,{wavenum},{wavetype},{opt1},{opt2},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10},{val11},{val12},{val13}" + return self.run(command, **kwargs) + + def biot(self, label: str = "", **kwargs): + r"""Calculates the Biot-Savart source magnetic field intensity. + + Mechanical APDL Command: `BIOT `_ + + **Command default:** + + .. _BIOT_default: + + Calculate the H:sub:`s` field upon encountering the first :ref:`solve` command to produce a source + field. + + Parameters + ---------- + label : str + Controls the Biot-Savart calculation: + + * ``NEW`` - Calculate the magnetic source field intensity (H:sub:`s` ) from the selected set of + source elements to the selected set of nodes. Overwrite any existing H:sub:`s` field values. + + * ``SUM`` - Calculate the H:sub:`s` field from the selected set of source elements to the selected + set of nodes. Accumulate with any existing H:sub:`s` field values. + + Notes + ----- + + .. _BIOT_notes: + + Calculates the Biot-Savart source magnetic field intensity (H:sub:`s` ) at the selected nodes from + the selected source elements. The calculation is done at the time the :ref:`biot` command is issued. + + Source elements include primitives described by element ``SOURC36``, and coupled-field elements + ``SOLID5``, ``LINK68``, and ``SOLID98``. Current conduction elements do not have a solved-for + current distribution from which to calculate a source field until after the first substep. Inclusion + of a current conduction element H:sub:`s` field will require a subsequent :ref:`biot`,SUM command + (with ``SOURC36`` elements unselected) and a :ref:`solve` command. + + The units of H:sub:`s` are as specified by the current :ref:`emunit` command setting. + + This command is also valid in PREP7. + + Distributed-Memory Parallel (DMP) Restriction When used with ``SOLID5``, ``LINK68``, or ``SOLID98``, + the :ref:`biot` command is not supported in a + DMP solution. + """ + command = f"BIOT,{label}" + return self.run(command, **kwargs) + + def dfswave( + self, + kcn: str = "", + radius: str = "", + psdref: str = "", + dens: str = "", + sonic: str = "", + incang: str = "", + npara: str = "", + sampopt: str = "", + **kwargs, + ): + r"""Specifies the incident planar waves with random phases for a diffuse sound field. + + Mechanical APDL Command: `DFSWAVE `_ + + Parameters + ---------- + kcn : str + Local coordinate system: + + * ``N`` - Coordinate system number. Default = 0. + + * ``DELETE`` - Delete defined incident diffused planar waves. + + radius : str + Radius of the reference sphere on which the incident planar waves are distributed with equal + energy. Defaults to 50 x the half-maximum dimension of the structural panel. + + psdref : str + Reference power spectral density. Default = 1. + + dens : str + Mass density of incident planar wave media. Default = 1.2041 kg/m :sup:`3`. + + sonic : str + Sound speed in incident planar wave media. Default = 343.24 m/s) + + incang : str + Maximum incident angle (0 :sup:`o` <= ``degree`` <= 180 :sup:`o` ) against the positive z axis + in the local coordinate system ``KCN``. Default = 89 :sup:`o`. + + npara : str + Number of divisions on the reference sphere with cutting planes parallel to the x-y coordinate + plane of the local coordinate system. Default = 20. + + sampopt : str + Random sampling option: + + * ``ALL`` - Initializes the random generator of incident planar wave phases and samples the phases + at each solving frequency. + + * ``MULT`` - Initializes the random generator of incident planar wave phases at the first frequency + and samples the phases at each solving frequency. + + * ``MONO`` - Initializes the random generator of incident planar wave phases and samples the phases + only once at first solving frequency so that the same phases are used over the whole frequency range + for each incident planar wave. + + Notes + ----- + + .. _DFSWAVE_notes: + + Issue the :ref:`dfswave` command to activate a diffuse sound field. (The :ref:`awave` command does + not activate a diffuse sound field.) + + The ``SURF154`` surface element must be defined on the surface of the structural solid element for + the excitation. + + The acoustic elements and the absorbing boundary condition must be defined in the open acoustic + domain. Do not define the acoustic domain on the excitation side. + + The :ref:`pras` and :ref:`plas` commands calculate the average transmission loss for multiple + sampling phases at each frequency over the frequency range. + + The symmetry of a panel structure cannot be used to reduce the simulation size, as the incident + plane waves have varying random phase angles. The z axis of the Cartesian coordinate system ( + ``KCN`` ) must be consistent with the panel``s outward normal unit vector at the center of the + panel``s sending side. + """ + command = ( + f"DFSWAVE,{kcn},{radius},{psdref},{dens},{sonic},{incang},{npara},{sampopt}" + ) + return self.run(command, **kwargs) + + def fluread( + self, + fname: str = "", + ext: str = "", + kdim: str = "", + kout: int | str = "", + limit: str = "", + listopt: str = "", + **kwargs, + ): + r"""Reads one-way Fluent-to-Mechanical APDL coupling data via a :file:`.cgns` file with one-side fast Fourier + transformation complex pressure peak value. + + Mechanical APDL Command: `FLUREAD `_ + + Parameters + ---------- + + fname : str + File name and directory path of a one-way Fluent-to-Mechanical APDL coupling data file (248 + characters maximum, including the characters needed for the directory path). An unspecified + directory path defaults to the working directory; in this case, you can use all 248 characters + for the file name. Defaults to :file:`jobname`. + + ext : str + File name extension of the one-way Fluent-to-Mechanical APDL coupling data file. Defaults to + :file:`.cgns` ). + + kdim : str + Interpolation data for mapping. A value of 0 (default) or 2 applies 2D interpolation (where + interpolation occurs on a surface). + + kout : int or str + Outside region results for mapping: + + * ``0`` - Use the value(s) of the nearest region point for points outside of the region. This + behavior is the default. + + * ``1`` - Set results extrapolated outside of the region to zero. + + limit : str + Number of nearby nodes considered for mapping interpolation. Minimum = 5. Default = 20. + + Lower values reduce processing time; however, some distorted or irregular meshes require a + higher value in cases where three nodes are encountered for triangulation. + + listopt : str + Type of items picked: + + * ``(blank)`` - No listing (default). + + * ``SOURCE`` - List the node coordinates and complex pressure values on the Fluent source side + during the solution. + + * ``TARGET`` - List the node coordinates and complex pressure values on the mapped Mechanical APDL target + side during the solution. + + * ``BOTH`` - List the node coordinates and complex pressure values on both the Fluent source side + and the mapped Mechanical APDL target side during the solution. + + Notes + ----- + + .. _FLUREAD_notes: + + The :ref:`fluread` command reads one-way Fluent-to-Mechanical APDL coupling data from a + :file:`.cgns` + file. The Fluent one-side fast Fourier transformation (FFT) peak complex pressure values are + mapped to the Mechanical APDL structure model during the acoustic-structural solution at each FFT + frequency. + + The command can be used only for the model with the acoustic elements. + + To apply complex pressure to the structure model, define the ``SURF154`` surface element, then + define the one-way coupling interface ( :ref:`sf`,,FSIN) on the element. + + You can define the solving frequency range via the ``HARFRQ`` command. The solver selects the FFT + frequencies between the beginning and ending frequencies. The number of substeps is determined by + the number of FFT frequencies over the frequency range. The number of substeps defined via the + :ref:`nsubst` command is overwritten. + + For better mapping performance, consider the following: + + * Calculations for out-of-bound points require much more processing time than do points that are + within bounds. + + * For each point in the structural destination mesh, the command searches all possible triangles in + the Fluent source mesh to find the best triangle containing each point, then performs a linear + interpolation inside this triangle. For faster and more accurate results, consider your + interpolation method and search criteria carefully. (See ``LIMIT``.) + + It is possible to apply one-way coupling excitation to multiple frequencies. The one-side FFT peak + complex pressure values are necessary to do so. + """ + command = f"FLUREAD,,{fname},{ext},{kdim},{kout},{limit},{listopt}" + return self.run(command, **kwargs) + + def ic( + self, + node: str = "", + lab: str = "", + value: str = "", + value2: str = "", + nend: str = "", + ninc: str = "", + **kwargs, + ): + r"""Specifies initial conditions at nodes. + + Mechanical APDL Command: `IC `_ + + Parameters + ---------- + node : str + Node at which initial condition is to be specified. If ALL, apply to all selected nodes ( + :ref:`nsel` ). If ``NODE`` = P, graphical picking is enabled and all remaining command fields + are ignored (valid only in the GUI). A component name may be substituted for ``NODE``. + + lab : str + Degree-of-freedom label for which the initial condition is to be specified. If ALL, use all + appropriate labels. + + * **Structural labels** : UX, UY, or UZ (displacements); ROTX, ROTY, or ROTZ (rotations); HDSP + (hydrostatic pressure); PRES (pore pressure) + * For structural static and transient analyses, specify translational and rotational velocities as + initial conditions using these labels: VELX, VELY, VELZ (translational velocities); OMGX, OMGY, + OMGZ (rotational velocities). + * For structural transient analysis, specify translational and rotational accelerations as initial + conditions using these labels: ACCX, ACCY, ACCZ (translational accelerations); DMGX, DMGY, DMGZ + (rotational accelerations). + * The velocity and acceleration initial conditions are not included with ``Lab`` = ALL. + * **Thermal labels** : TEMP, TBOT, TE2, TE3,..., TTOP (temperature) + * **Magnetic labels** : MAG (scalar magnetic potential); AZ (vector magnetic potential) + * **Diffusion label** : CONC (concentration) + * **Acoustic label** : ENKE (acoustic energy density) + + value : str + Initial value of the degree of freedom. Defaults to the program default for that degree of + freedom (0.0 for structural analysis, :ref:`tunif` for thermal analysis, etc.). Values are in + the nodal coordinate system and in radians for rotational degrees of freedom. + + value2 : str + Second-order degree of freedom value, mainly used for non-structural DOF where VELX can't be + used. Defaults to the program default for that degree of freedom (0.0 for structural analysis). + Values are in the nodal coordinate system and in radians/time for rotational degrees of freedom. + + nend : str + Specifies the same initial condition values at the range of nodes from ``NODE`` to ``NEND`` + (defaults to ``NODE`` ), in steps of ``NINC`` (defaults to 1). + + ninc : str + Specifies the same initial condition values at the range of nodes from ``NODE`` to ``NEND`` + (defaults to ``NODE`` ), in steps of ``NINC`` (defaults to 1). + + Notes + ----- + + .. _IC_notes: + + The :ref:`ic` command specifies initial conditions, which are the initial values of the specified + degrees of freedom. It is valid only for a static analysis and full method transient analysis ( + :ref:`timint`,ON and :ref:`trnopt`,FULL). For the transient, the initial value is specified at the + beginning of the first load step, that is, at time = 0.0. + + If constraints ( :ref:`d`, :ref:`dsym`, etc.) and initial conditions are applied at the same node, + the constraint specification overrides. Exercise caution when specifying constraints. The degree-of- + freedom values start from zero, or the first value given in the table when table name is specified. + To match the nonzero initial condition value with the initial value for degree-of-freedom + constraint, use a table for the degree-of-freedom constraint. + + For thermal analyses, any :ref:`tunif` specification should be applied before the :ref:`ic` command; + otherwise, the :ref:`tunif` specification is ignored. If the :ref:`ic` command is input before any + :ref:`tunif` specification, use the :ref:`icdele` command and then reissue any :ref:`tunif` + specification and then follow with the :ref:`ic` command. + + When issuing the :ref:`ic` command for elements ``SOLID278`` `Layered Thermal Solid + `_ + and ``SOLID279`` `Layered Thermal Solid + `_ + with through-the-thickness degrees of freedom (KEYOPT(3) = 2), layers are always interpolated + linearly based on the location of the degrees of freedom. + + Define consistent initial conditions. For example, if you define an initial velocity at a single + degree of freedom, the initial velocity at every other degree of freedom will be 0.0, potentially + leading to conflicting initial conditions. In most cases, you should define initial conditions at + every unconstrained degree of freedom in your model. If you define an initial condition for any + degree of freedom at the pilot node of a rigid body (see `Modeling Rigid Bodies + `_ + in the `Contact Technology Guide + `_ for the + definition of rigid body), then the same initial condition must also be + defined for the same degree of freedom on all other nodes of the rigid body. + + After a solution has been performed, the specified initial conditions are overwritten by the actual + solution and are no longer available. You must respecify them if you want to perform a subsequent + analysis. You may want to keep a database file saved prior to the first solution for subsequent + reuse. + + If you use the :ref:`cdwrite` command to archive your model, initial displacements, temperatures, + etc. specified via the :ref:`ic` command are not written to the archive file; initial velocities and + accelerations are written. + + This command is also valid in PREP7. + """ + command = f"IC,{node},{lab},{value},{value2},{nend},{ninc}" + return self.run(command, **kwargs) + + def icdele(self, **kwargs): + r"""Deletes initial conditions at nodes. + + Mechanical APDL Command: `ICDELE `_ + + Notes + ----- + + .. _ICDELE_notes: + + Deletes all initial conditions previously specified with the :ref:`ic` or :ref:`icrotate` command at + all nodes. + + This command is also valid in PREP7. + """ + command = "ICDELE" + return self.run(command, **kwargs) + + def iclist( + self, node1: str = "", node2: str = "", ninc: str = "", lab: str = "", **kwargs + ): + r"""Lists the initial conditions. + + Mechanical APDL Command: `ICLIST `_ + + Parameters + ---------- + node1 : str + List initial conditions for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + initial conditions for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). A component name may be substituted for ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + node2 : str + List initial conditions for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + initial conditions for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). A component name may be substituted for ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + ninc : str + List initial conditions for nodes ``NODE1`` to ``NODE2`` (defaults to ``NODE1`` ) in steps of + ``NINC`` (defaults to 1). If ``NODE1`` = ALL (default), ``NODE2`` and ``NINC`` are ignored and + initial conditions for all selected nodes ( :ref:`nsel` ) are listed. If ``NODE1`` = P, + graphical picking is enabled and all remaining command fields are ignored (valid only in the + GUI). A component name may be substituted for ``NODE1`` ( ``NODE2`` and ``NINC`` are ignored). + + lab : str + Label identifying the initial condition to list out: + + * ``DISP`` - Displacements, temperature, etc. (default). + + * ``VELO`` - Velocities. + + * ``ACC`` - Accelerations. + + Notes + ----- + + .. _ICLIST_notes: + + Lists the initial conditions specified by the :ref:`ic` or :ref:`icrotate` command. Listing + applies to all the selected nodes ( :ref:`nsel` ) and DOF labels. :ref:`iclist` is not the same as + the :ref:`dlist` command. All the initial conditions including the default conditions are listed for + the selected nodes. + + This command is valid in any processor. + """ + command = f"ICLIST,{node1},{node2},{ninc},{lab}" + return self.run(command, **kwargs) + + def icrotate( + self, + node: str = "", + omega: str = "", + x1: str = "", + y1: str = "", + z1: str = "", + x2: str = "", + y2: str = "", + z2: str = "", + vx: str = "", + vy: str = "", + vz: str = "", + accel: str = "", + **kwargs, + ): + r"""Specifies initial velocity at nodes as a sum of rotation about an axis and translation. + + Mechanical APDL Command: `ICROTATE `_ + + Parameters + ---------- + node : str + Node at which the initial velocity is to be specified. If ALL, apply to all selected nodes ( + :ref:`nsel` ). A component name may be input for ``NODE``. + + omega : str + Scalar rotational velocity about the rotational axis. + + x1 : str + Coordinates (in the global Cartesian coordinate system) of the beginning point of the rotational + axis vector. + + y1 : str + Coordinates (in the global Cartesian coordinate system) of the beginning point of the rotational + axis vector. + + z1 : str + Coordinates (in the global Cartesian coordinate system) of the beginning point of the rotational + axis vector. + + x2 : str + Coordinates (in the global Cartesian coordinate system) of the end point of the rotational axis + vector. + + y2 : str + Coordinates (in the global Cartesian coordinate system) of the end point of the rotational axis + vector. + + z2 : str + Coordinates (in the global Cartesian coordinate system) of the end point of the rotational axis + vector. + + vx : str + Initial translational velocity in direction x of the nodal coordinate system. + + vy : str + Initial translational velocity in direction y of the nodal coordinate system. + + vz : str + Initial translational velocity in direction z of the nodal coordinate system. + + accel : str + Key to initialize acceleration due to centrifugal effects: + + * ``(blank)`` - Do not initialize acceleration (default). + + * ``CENT`` - Initialize acceleration due to centrifugal effects along with the initial velocity. + + Notes + ----- + + .. _ICROTATE_notes: + + The :ref:`icrotate` command specifies initial velocity for all translational degrees of freedom of + the specified nodes. The velocity value is a combination of velocity due to rotation about an axis + and translation. The velocity at the node is calculated as: + + :math:`equation not available` + + where + + * v :sup:`N` = velocity of node ``N`` in the nodal coordinate system + * v :sup:`trans` = translational velocity input as [ ``Vx``, ``Vy``, ``Vz`` ] + * ω = scalar angular velocity input as ``OMEGA`` + * x :sup:`1` and x :sup:`2` denote the coordinates of points prescribing the beginning [ ``X1``, + ``Y1``, ``Z1`` ] and end [ ``X2``, ``Y2``, ``Z2`` ] of the rotation axis + * x :sup:`N` denotes the coordinates of node ``N`` + + All coordinates are input in the global Cartesian coordinate system, and the velocity due to + rotation is then converted to the nodal coordinate system and added to the prescribed translation. + + If ``ACCEL`` = CENT is specified, acceleration due to centrifugal effects is initialized as well. + The acceleration at node a :sup:`N` is initialized as: + + :math:`equation not available` + + The :ref:`icrotate` command is valid only for static analysis and full method transient analysis ( + :ref:`timint`,ON with :ref:`trnopt`,FULL). The initial value is specified at the beginning of the + first load step; that is, at time = 0.0. + + The command calculates the nodal velocities and saves them in the database as if the :ref:`ic` + command had been used to calculate these velocities. Thus, when the :file:`Jobname.CDB` or + :file:`Jobname.DB` file is written, the velocities prescribed by the :ref:`icrotate` command appear + as :ref:`ic` commands. All assumptions, recommendations, and restrictions for the :ref:`ic` command + are also true for the :ref:`icrotate` command. + + This command is also valid in PREP7. + """ + command = f"ICROTATE,{node},{omega},{x1},{y1},{z1},{x2},{y2},{z2},{vx},{vy},{vz},{accel}" + return self.run(command, **kwargs) + + def mrpm(self, val1: str = "", **kwargs): + r"""Defines the revolutions per minute (RPM) for a machine rotation. + + Mechanical APDL Command: `MRPM `_ + + Parameters + ---------- + val1 : str + The RPM value (no default). + + Notes + ----- + + .. _MRPM_notes: + + A different RPM value can be defined at each load step. The RPM value is used to postprocess the + equivalent radiated power from the structural surface (the :ref:`pras` and :ref:`plas` commands) or + the radiated sound power level (the :ref:`prfar` and :ref:`plfar` commands). + """ + command = f"MRPM,{val1}" + return self.run(command, **kwargs) + + def osresult( + self, item: str = "", comp: str = "", freq: str = "", cname: str = "", **kwargs + ): + r"""Controls the selected result data written to the database. + + Mechanical APDL Command: `OSRESULT `_ + + Parameters + ---------- + item : str + Item to output to the database. See :ref:`OSRESULT_tab_1`. + + comp : str + Component of ``Item`` to output to the database. See :ref:`OSRESULT_tab_1`. + + freq : str + Frequency to output to the database. + + * ``n`` - Writes every ``n`` th and last substep of each load step. + + * ``-n`` - Writes up to ``n`` equally spaced substeps of each load step. + + * ``ALL`` - Writes every substep. + + * ``LAST`` - Writes the last substep of each load step (default). + + cname : str + The name of an element component ( :ref:`cm` ) defining the set of elements for which this + specification is active. If not specified, the set is all elements. + + Notes + ----- + + .. _OSRESULT_notes: + + :ref:`osresult` controls output to the results database for the selected result defined by the item + and component combination. The command activates output of the selected result for the specified + substeps and elements. Multiple commands for the same result are cumulative. No selected results are + written to the database unless specified via an :ref:`osresult` command. + + :ref:`osresult`,ERASE deletes the existing output specifications. + + :ref:`osresult`,STATUS lists the current set of selected result specifications. + + The output of selected results is valid for static ( :ref:`antype`,STATIC) and transient ( + :ref:`antype`,TRANS) analysis types. + + To specify other results to output to the database, see :ref:`outres`. + + Element quantities specified via :ref:`outres` can be redundant to those specified via + :ref:`osresult`. Avoid specifying redundant quantities, as they are stored and processed separately. + + This command is also valid in PREP7. + + .. _OSRESULT_tab_1: + + OSRESULT - Item and Component Labels + ************************************ + + .. flat-table:: **Component Name Method** + :header-rows: 1 + + * - **Item** + - **Comp** + - **Description** + * - ERASE + - -- + - Erases all selected result output specifications. + * - STATUS + - -- + - Lists the current set of selected result output specifications. + * - SVAR + - 1,2,3,..., ``N`` + - State variable number. + * - FLD + - UF01, UF02,..., UF09 + - User-defined field variables + + """ + command = f"OSRESULT,{item},{comp},{freq},{cname}" + return self.run(command, **kwargs) + + def outgeom(self, item: str = "", freq: str = "", **kwargs): + r"""Controls geometry-related data written to the results file. + + Mechanical APDL Command: `OUTGEOM `_ + + Parameters + ---------- + item : str + Geometry data item for file write control: + + * ``MAT`` - Material Properties. + + * ``ERASE`` - Reset :ref:`outgeom` specifications to their default values. + + * ``STAT`` - List the current :ref:`outgeom` specifications. + + freq : str + Specifies how often to write the specified geometry data: + + * ``NONE`` - Suppress writing of the specified item for all substeps. + + * ``ALL`` - Write the data of the specified item for every substep. + + Notes + ----- + + .. _OUTGEOM_notes: + + The :ref:`outgeom` command controls writing of the specified geometry ``Item`` to the results file. + The geometry items correspond to the geometry records that are included in the results file (see the + GEO records of the results file as described in ). + + The command generates a specification for controlling data storage by either activating storage of + the specified geometry item ( ``Freq`` = ALL) or by suppressing storage of that item ( ``Freq`` = + NONE). + + You can issue multiple :ref:`outgeom` commands in an analysis. After the initial command creates the + storage specification, subsequent :ref:`outgeom` commands modify the specification set. The command + processes your specifications in the order in which you input them. If you specify a given ``Item`` + twice, output is based upon the last specification. + + In addition to :ref:`outgeom`, :ref:`outpr` and :ref:`outres` also control solution output. You can + issue up to 50 of these output-control commands (any combination of the three) in an analysis. + + :ref:`outgeom`,ERASE erases the existing output specifications and resets the counted number of + :ref:`outgeom` commands to zero. + + When material property information is not written to the results file ( :ref:`outgeom`,MAT,NONE), + clearing the database via :ref:`clear` and reading in a set of data in the general postprocessor ( + :ref:`post1` ) via the :ref:`set` command results in no material property data being stored in the + database. In this case, the lack of material data prevents a successful solve from occurring with + the modified database, and the results file is only applicable for carrying out post-processing. + + The :ref:`outgeom` command is also valid in :ref:`prep7`. + """ + command = f"OUTGEOM,{item},{freq}" + return self.run(command, **kwargs) + + def outpr(self, item: str = "", freq: str = "", cname: str = "", **kwargs): + r"""Controls the solution printout. + + Mechanical APDL Command: `OUTPR `_ + + Parameters + ---------- + item : str + Item for print control: + + * ``BASIC`` - Basic quantities (nodal DOF solution, nodal reaction loads, and element solution) + (default). + + * ``NSOL`` - Nodal DOF solution. + + * ``RSOL`` - Nodal reaction loads. + + * ``ESOL`` - Element solution. + + * ``NLOAD`` - Element nodal loads. When `nonlinear stabilization + `_ is active, + the stabilization force/moments are also printed. + + * ``SFOR`` - Stabilization force/moment at the applicable nodes (valid only when `nonlinear + stabilization `_ + is active). + + * ``VENG`` - Element energies. When `nonlinear stabilization + `_ is active, + the energy dissipation due to stabilization is also printed. + + * ``RSFO`` - Result section force/moment output (valid only when a `result section + `_ is defined). + Result section output is always written to a file named :file:`JobnameSECF`. + + * ``V`` - Nodal velocity (applicable to structural transient analysis only ( :ref:`antype`,TRANS)). + + * ``A`` - Nodal acceleration (applicable to structural transient analysis only ( + :ref:`antype`,TRANS)). + + * ``ALL`` - All of the above solution items. + + freq : str + Print solution for this item every ``Freq`` :sup:`th` (and the last) substep of each load step. + If - ``n``, print up to ``n`` equally spaced solutions (only applies to static or full transient + analyses when automatic time stepping is enabled). If NONE, suppress all printout for this item + for this load step. If ALL, print solution for this item for every substep. If LAST, print + solution for this item only for the last substep of each load step. For a modal analysis, use + NONE or ALL. + + cname : str + Name of the component, created with the :ref:`cm` command, defining the selected set of nodes or + elements for which this specification is active. If blank, the set is all entities. + + The component named must be of the same type as the item, i.e. nodal or element. A component + name is not allowed with the BASIC, RSFO, or ALL labels. + + Notes + ----- + + .. _OUTPR_notes: + + Controls the solution items to be printed, the frequency with which they are printed (in static, + transient, or full harmonic analyses), and the set of nodes or elements to which this specification + applies (in static, transient, or full harmonic analyses). An item is associated with either a node + ( :ref:`nsol`, :ref:`rforce`, V, and A items) or an element (all of the remaining items). The + specifications are processed in the order that they are input. Use :ref:`outpr`,STAT to list the + current specifications and use :ref:`outpr`,ERASE to erase all the current specifications. + + In addition to :ref:`outpr`, :ref:`outres` and :ref:`outgeom` also control solution output. You can + issue up to 50 of these output-control commands (any combination of the three) in an analysis. + + As described above, :ref:`outpr` writes some or all items (depending on analysis type) for all + elements. To restrict the solution printout, use :ref:`outpr` to selectively suppress ( ``Freq`` = + NONE) the writing of solution data, or first suppress the writing of all solution data ( + :ref:`outpr`,ALL,NONE) and then selectively turn on the writing of solution data with subsequent + :ref:`outpr` commands. + + If the generalized plane strain feature is active and :ref:`outpr` is issued, the change of fiber + length at the ending point during deformation and the rotation of the ending plane about X and Y + during deformation will be printed if any displacement at the nodes is printed. The reaction forces + at the ending point will be printed if any reaction force at the nodes is printed. + + Nodal reaction loads ( ``Item`` = RSOL) are processed according to the specifications listed for the + :ref:`prrsol` command. + + Result printouts for interactive sessions are suppressed for models with more than 10 elements + except when the printout is redirected to a file using the :ref:`output` command. + + This command is also valid in PREP7. + """ + command = f"OUTPR,{item},{freq},{cname}" + return self.run(command, **kwargs) + + def outres( + self, + item: str = "", + freq: str = "", + cname: str = "", + nsvar: str = "", + dsubres: str = "", + **kwargs, + ): + r"""Controls the solution-result data written to the database. + + Mechanical APDL Command: `OUTRES `_ + + Parameters + ---------- + item : str + Solution item for database and file-write control: + + * ``ALL`` - All solution items except LOCI, SVAR, and NAR (default). + + * ``BASIC`` - Write only NSOL, RSOL, NLOAD, STRS, FGRAD, and FFLUX records to the results file and + database. + + * ``ERASE`` - Resets :ref:`outres` specifications to their default values. + + * ``STAT`` - Lists the current :ref:`outres` specifications. + + * ``NSOL`` - Nodal degree-of-freedom solution. + + * ``RSOL`` - Nodal reaction loads. + + * ``V`` - Nodal velocity (applicable to structural transient analysis only ( :ref:`antype`,TRANS)). + + * ``A`` - Nodal acceleration (applicable to structural transient analysis only ( + :ref:`antype`,TRANS)). + + * ``CINT`` - All available results generated by :ref:`cint`. + + * ``SVAR`` - State variables (used with supported `subroutines that customize material behavior + `_ ). + + * ``ESOL`` - Enables or disables all of the following element-solution items. (These items can also be + individually enabled or disabled.) + + * ``NLOAD`` - Element nodal, input constraint, and force loads (also used with POST1 commands + :ref:`prrfor`, :ref:`nforce`, and :ref:`fsum` to calculate reaction loads). + + * ``STRS`` - Element nodal stresses. + + * ``EPEL`` - Element elastic strains. + + * ``EPTH`` - Element thermal, initial, and swelling strains. + + * ``EPPL`` - Element plastic strains. + + * ``EPCR`` - Element creep strains. + + * ``EPDI`` - Element diffusion strains. + + * ``FGRAD`` - Element nodal gradients. + + * ``FFLUX`` - Element nodal fluxes. + + * ``LOCI`` - Integration point locations. + + * ``VENG`` - Element energies. + + * ``MISC`` - Element miscellaneous data ( :ref:`etable` SMISC and NMISC items). + + * ``FMAG`` - Electromagnetic nodal forces. + + * ``CURD`` - Element source current density. + + * ``NLDAT`` - Element nonlinear data. + + * ``EHEAT`` - Element heat generation rate. + + * ``ETMP`` - Element temperatures. + + * ``SRFS`` - Element surface stresses. + + * ``CONT`` - Element contact data. + + * ``BKSTR`` - Element backstresses. Enabling this output also requires that you enable EPPL. + + * ``EANGL`` - Element Euler angles. + + * ``AESO`` - Enables or disables all of the following advanced element-solution output items. (These items cannot be individually enabled or disabled.) + + * BKS - Back-stress for kinematic hardening. + * CDM - Damage variable for Mullins effect. + * ESIG - BIOT's effective stress. + * FFLX - Fluid flow flux in poromechanics. + * FICT - Fictive temperature. + * FSVAR - Fluence state variables. + * MPLS - Microplane damage. + * NS - Nominal strain. + * PDMG - Progressive damage parameters. + * PFC - Failure criteria based on the effective stresses in the damaged material. + * PMSV - Permeability state variables. + * SEND - Energy record. + * TF - Thermal flux. + * TG - Thermal gradient. + * YSIDX - Yield status for geomechanical materials. + + * ``NAR`` - Enables or disables all of the following nodal-averaged solution items. (These items can also be + individually enabled or disabled.) + + * ``NDST`` - Nodal-averaged stresses. + + * ``NDEL`` - Nodal-averaged elastic strains. + + * ``NDPL`` - Nodal-averaged plastic strains. + + * ``NDCR`` - Nodal-averaged creep strains. + + * ``NDTH`` - Nodal-averaged thermal and swelling strains. + + freq : str + Specifies how often (that is, at which substeps) to write the specified solution item. The + following values are valid: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + cname : str + The name of the component (created via :ref:`cm` ) defining the selected set of elements or + nodes for which this specification is active. If not specified, the set is all entities. A + component name is not allowed with the ALL, BASIC, or RSOL items. + + nsvar : str + The number of user-defined state variables ( :ref:`tb`,STATE) to be written to the results file. + Valid only when ``Item`` = SVAR and user-defined state variables exist. The specified value + cannot exceed the total number of state variables defined; if no value is specified, all user- + defined state variables are written to the results file. This argument acts on all sets of user- + defined state variables that exist for the model. + + dsubres : str + Specifies whether to write additional results in :file:`Jobname.DSUB` during a substructure or CMS + `use pass + `_ + in a transient or harmonic analysis. + + * ```` - Write the nodal degree-of-freedom solution in :file:`Jobname.DSUB` (default). + + * ``ALL`` - In addition to the nodal degree-of-freedom solution, also write necessary data to + compute quantities using nodal velocity and nodal acceleration (damping force, inertial force, + kinetic energy, etc.) in the subsequent expansion pass. For more information, see `Step 3: Expansion + Pass + `_ + + Notes + ----- + + .. _OUTRES_notes: + + :ref:`outres` controls following output parameters: + + * The solution item ( ``Item`` ) to write to the database (and to the reduced displacement and + results files) + + * The frequency ( ``Freq`` ) at which the solution item is written (applicable to static, transient, + or full harmonic analyses) + + * The set of elements or nodes ( ``Cname`` ) to which your specification applies. + + The command generates a specification for controlling data storage for each substep, activating + storage of the specified solution item for the specified substeps of the solution and suppressing + storage of that item for all other substeps. + + You can issue :ref:`outres` multiple times in an analysis. After the initial command creating the + storage specification, subsequent :ref:`outres` commands modify the specification set for each + substep. The command processes your specifications at each substep in the order in which you input + them. If you specify a given solution item twice, output is based upon the last specification. + Therefore, issue multiple :ref:`outres` commands carefully and in the proper sequence. + + In addition to :ref:`outres`, these commands also control solution output: :ref:`outpr`, + :ref:`outgeom`, and :ref:`osresult`. + + You can issue up to 50 output-control commands for :ref:`outres`, :ref:`outpr`, :ref:`outgeom` in an + analysis. There is no limit on the number of :ref:`osresult` commands. + + :ref:`outres`,ERASE erases the existing output specifications and resets the counted number of + :ref:`outres` commands to zero. The ERASE argument works in a similar manner for :ref:`outpr`, + :ref:`outgeom`, and :ref:`osresult`. + + A given :ref:`outres` command generally has no effect on solution items not specified. For example, + an :ref:`outres`,ESOL,LAST command does not affect NSOL data; that is, it neither activates nor + suppresses NSOL data storage in any substep. An exception to this behavior involves the EANGL + solution item. + + :ref:`outres` controls element Euler angle (EANGL) data output as follows: + + * When ``Freq`` = NONE, no element Euler angles are output at any substeps. + + * Without Euler angles, element results postprocessing can occur in the element solution coordinate + system only (that is, :ref:`rsys` has no effect on element results); therefore, nodal averaging of + element solution items may not be applicable when element solution coordinate systems are not + uniform. + + * When ``Freq`` = any other value (including the command default), element Euler angles are output + at substeps specified by ``Freq``, and at any substeps where one or more tensorial element + solution items (STRS, EPEL, EPTH, EPPL, EPCR, EPDI, FGRAD, FFLUX, and AESO) are output. + + Additional results in the :file:`Jobname.DSUB` file (DSUBres = ALL) can only be requested in the + first load step. + + In the results-item hierarchy, certain items are subsets of other items. For example, element + solution (ESOL) data is a subset of all (ALL) solution data. An :ref:`outres`,ALL command can + therefore affect ESOL data. Likewise, an :ref:`outres` command that controls ESOL data can affect a + portion of all data. + + The :ref:`example ` :ref:`outres` commands illustrate the interrelationships between + solution items and the necessity of issuing :ref:`outres` thoughtfully. + + To suppress all data at every substep, issue the :ref:`outres`,ALL,NONE command. ( + :ref:`outres`,ERASE does not suppress all data at every substep.) + + The NSOL, RSOL, V, and A solution items are associated with nodes. The CINT solution item is + associated with fracture. All remaining solution items are associated with elements. + + Enabling nodal-averaged results ( ``Item`` = NAR or any of the associated labels) generally reduces + the results file size, provided the equivalent element-based results are concurrently disabled. When + nodal-averaged results are enabled, element values for stress and strain are averaged and stored as + nodal values. Some limitations apply when using nodal averaged results. For more information and an + example, see `Nodal-Averaged Results + `_ + + The boundary conditions (constraints and force loads) are written to the results file only if either + nodal or reaction loads (NLOAD or RSOL items) are also written. + + When specifying a ``Freq`` value, observe the following: + + * For a modal analysis, only NONE or ALL are valid. + + * If you issue multiple :ref:`outres` commands during an analysis, you cannot specify a :ref:`key + time array parameter (% ` ``array``) in a given :ref:`outres` command and then specify a + different ``Freq`` option in a subsequent :ref:`outres` command. + + For additive manufacturing analyses during the build step ( :ref:`amstep`,BUILD), ``Freq`` refers to + the layer number (for example, output ALL layers, LAST layer, or every ``N`` :sup:`th` layer). + + To specify selected results to output to the database, see :ref:`osresult`. + + :ref:`outres` is also valid in PREP7. + + **Example** + + .. _OUTRES_example: + + When issuing an :ref:`outres` command, think of a matrix in which you set switches on and off. When + a switch is on, a solution item is stored for the specified substep. When a switch is off, a + solution item is suppressed for a specified substep. + + Assuming a static ( :ref:`antype`,STATIC) analysis, this example shows how the matrix looks after + issuing each :ref:`outres` command in this six-substep solution. + + .. code:: apdl + + NSUBST,6 + OUTRES,ERASE + OUTRES,NSOL,2 + OUTRES,ALL,3 + OUTRES,ESOL,4 + SOLVE + + To simplify the example, only a subset of the available solution items appears in the matrix. + + :ref:`outres`,ERASE -- After issuing this command, the default output specifications are in effect, + as shown: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + :ref:`outres`,NSOL,2 -- This command modifies the initial specifications so that NSOL is enabled for + substeps 2, 4 and 6, and disabled for substeps 1, 3 and 5, as shown: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + :ref:`outres`,ALL,3 -- This command further modifies the specifications so that ALL is enabled for + substeps 3 and 6, and disabled for substeps 1, 2, 4 and 5, as shown: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + :ref:`outres`,ESOL,4 -- This command once again modifies the specifications so that ESOL is enabled + for the fourth and last substeps, and disabled for substeps 1, 2, 3 and 5, as shown: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + :ref:`solve` + + When obtaining the solution, results data are stored as follows: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + """ + command = f"OUTRES,{item},{freq},{cname},,{nsvar},{dsubres}" + return self.run(command, **kwargs) + + def rescontrol( + self, + action: str = "", + ldstep: str = "", + frequency: str = "", + maxfiles: int | str = "", + maxtotalfiles: str = "", + filetype: str = "", + **kwargs, + ): + r"""Controls file writing for multiframe restarts. + + Mechanical APDL Command: `RESCONTROL `_ + + Parameters + ---------- + action : str + Command action: + + * ``DEFINE`` - Specifies how often :file:`.xnnn` restart files (default) or :file:`.rdnn` remeshing + database files (for `nonlinear mesh adaptivity + `_ analysis) are + written for a load step. The file type controlled by this command is determined by ``Filetype``. + + * ``FILE_SUMMARY`` - Prints the substep and load-step information for all :file:`.xnnn` or + :file:`.rdnn` files for the current jobname in the current directory. If specified, all other + arguments are ignored. + + * ``STATUS`` - Issuing the command lists the current status in the tables of restart controls + specified previously by :ref:`rescontrol`. If this option is specified, all other arguments are + ignored. + + * ``NORESTART`` - Cleans up some of the restart files after a distributed-memory parallel (DMP) + solution. (Not valid for `nonlinear mesh adaptivity + `_.) + + The master process will not have the following files in the working directory at the end of the run: + :file:`.esav`, :file:`.osav`, :file:`.xnnn`, :file:`.rdb`, :file:`.ldhi`. The worker processes will + not have the following files in the working directory at the end of the run: :file:`.esav`, + :file:`.osav`, :file:`.xnnn`, :file:`.rst` (or :file:`.rth`, etc.). Some restart files are never + written, some are removed upon exiting the solution processor (for example, upon :ref:`finish` ), + and some are removed upon exiting the program. + + This option is useful for cleaning up files written by all distributed processes, especially when + you know that these restart files will not be needed later. If this option is specified, all other + arguments are ignored. + + If this option is used in a shared-memory parallel (SMP) environment, most restart files in the + working directory are removed. It has the same effect as issuing :ref:`rescontrol`,,NONE. + + * ``LINEAR`` - Same as ``Action`` = DEFINE, but for linear static applications only. For a linear + static analysis, the restart capability is normally not needed; however, it is typically needed when + a subsequent linear perturbation analysis is desired. By default, none of the restart files are + written for a linear static analysis. + + * ``DELETE`` - Delete the restart control specification corresponding to the ``Ldstep`` label on a + previous :ref:`rescontrol`,DEFINE command. + + ldstep : str + Specifies how the :file:`.xnnn` or :file:`.rdnn` files are written for the specified load steps. This option also affects how often the load history information is written to the :file:`.ldhi` file. + + * ``ALL`` - Write the :file:`.xnnn` or :file:`.rdnn` files at the same substep ``Frequency`` for all + load steps; write the load history information to the :file:`.ldhi` file for all load steps. For + :file:`.rdnn` files, this option is the default. + + * ``LAST`` - Write the :file:`.xnnn` or :file:`.rdnn` files for the last load step only; write load- + history information to the :file:`.ldhi` file for the last load step only. This option is the + default for nonlinear static and full transient analyses for :file:`.xnnn` files. If specified, all + remaining arguments are ignored. + + * ``N`` - Number that indicates how often the :file:`.xnnn` or :file:`.rdnn` files are written. + + Input a positive number to write the :file:`.xnnn` or :file:`.rdnn` files at the substep + ``Frequency`` indicated only for load step ``N``. Other load steps will be written at the default + substep frequency or at a frequency defined by a previous :ref:`rescontrol` specification. Load- + history information is written to the :file:`.ldhi` file only for load steps ``N``. + + Specifying a negative number (- ``N`` ) is valid for controlling :file:`.xnnn` files only. The files + are written for every ``N`` th load step at the specified substep ``Frequency``. The load history + information is written to the :file:`.ldhi` file every ``N`` th load step. This option is suitable + for restart applications in which more than a few hundred load steps are required. Compared to the + ALL and positive ``N`` options, it can save disk space, as the :file:`.ldhi` file is smaller and + fewer :file:`.xnnn` files are written. + + If ``Ldstep`` = - ``N``, all other ``Ldstep`` options specified by :ref:`rescontrol` are ignored and + the program follows the - ``N`` option (write load history information every ``N`` th load step). If + you want to change this pattern, issue :ref:`rescontrol`,DELETE, - ``N``, then issue another + :ref:`rescontrol` command with the desired ``Ldstep`` option. + + * ``NONE`` - No multiframe restart files ( :file:`.rdb`, :file:`.ldhi`, :file:`.xnnn` ) are created. + (Not valid for `nonlinear mesh adaptivity + `_ analysis.) + + This option is the default for mode-superposition analyses. The remaining arguments are ignored. + + For nonlinear static, linear static, and full transient analyses, this option enables a restart to + occur at the last or abort point (using the :file:`.emat`, :file:`.esav` or :file:`.osav`, and + :file:`.db` files). + + For mode-superposition transient analyses, this option allows a restart from the last point using + the :file:`.rdsp` and :file:`.db` files. + + frequency : str + Frequency at which the :file:`.xnnn` files are written at the substep level, or at which the :file:`.rdnn` files are written at the remeshing level: + + * ``NONE`` - Do not write :file:`.xnnn` files for this load step (not available for :file:`.rdnn` + files). + + * ``LAST`` - Write the :file:`.xnnn` files for the last substep of the load step only (default for + nonlinear static and full transient analyses), or write the :file:`.rdnn` files for the last remesh + of the load step only (default for `nonlinear mesh adaptivity + `_ analysis). + + * ``N`` - If ``N`` is positive, write the :file:`.xnnn` files at every ``N`` th substep of a load + step, or write the :file:`.rdnn` files at every ``N`` th remesh of a load step. + + If ``N`` is negative (not valid for :file:`.rdnn` files), write ``N`` equally spaced :file:`.xnnn` + files within a load step. + + In nonlinear static and full transient analyses, ``-N`` is valid only when automatic time stepping + is enabled ( :ref:`autots`,ON). + + In mode-superposition analyses, negative ``N`` is always valid. + + maxfiles : int or str + Maximum number of :file:`.xnnn` files to save within a load step ( not available for :file:`.rdnn` files): + + * ``-1`` - Overwrite existing :file:`.xnnn` files (default). The total maximum number of + :file:`.xnnn` files for one run is 999. If this number is reached before the analysis is complete, + the program will reset the :file:`.xnnn` file numbering back to 1 and continue to write + :file:`.xnnn` files; the program keeps the newest 999 restart files and overwrites the oldest + restart files. For this option, the maximum number of files can be changed to a number less than 999 + by setting the MAXTotalFiles argument. + + * ``0`` - Do not overwrite any existing :file:`.xnnn` files. The total maximum number of + :file:`.xnnn` files for one run is 999. If this number is reached before the analysis is complete, + the analysis continues but no longer writes any :file:`.xnnn` files. + + * ``N`` - Maximum number of :file:`.xnnn` files to keep for each load step. When ``N`` + :file:`.xnnn` files have been written for a load step, the program overwrites the first + :file:`.xnnn` file of that load step for subsequent substeps. ``N`` must be <= 999. If a total of + 999 restart files is reached before the analysis is complete, the analysis continues but writes no + additional :file:`.xnnn` files. + + maxtotalfiles : str + Total number of restart files to keep. Default = 999 for :file:`.xnnn` files and 99 for + :file:`.rdnn` files. This option is valid only when ``MAXFILES`` = -1 (default). + + Valid ``MAXTotalFiles`` values are 1 through 999 for :file:`.xnnn` files, and 1 through 99 for + :file:`.rdnn` files. + + When the total number of restart files written exceeds ``MAXTotalFiles``, the program resets the + :file:`.xnnn` or :file:`.rdnn` file numbering back to 1 and continues to write :file:`.xnnn` or + :file:`.rdnn` files. The newest files are retained and the oldest files are overwritten. + + The ``MAXtotalFiles`` value specified applies to all subsequent load steps. To reset it to the + default, reissue the command with ``MAXTotalFiles`` = 0 or some negative value. + + If ``MAXTotalFiles`` is set to different values at different load steps, and if the value of + ``MAXTotalFiles`` specified in the prior load step is larger than that of the current load step, + the program can only overwrite the current number of maximum restart files up to the number + ``MAXTotalFiles`` currently specified (which is smaller than the previous number). + + The recommended way to control the maximum number of restart files is to specify + ``MAXTotalFiles`` at the first load step and not vary it in subsequent load steps. Also, + ``MAXTotalFiles`` is best used when ``Ldstep`` = - ``N`` or ALL. + + filetype : str + The type of restart file to be controlled by this command. Valid only when ``Action`` = DEFINE: + + * ``XNNN`` - Control :file:`.xnnn` files (default). + + * ``RDNN`` - Control :file:`.rdnn` remeshing database files. Needed only for a `nonlinear mesh + adaptivity `_ + analysis. + + Notes + ----- + + .. _RESCONTROL_notes: + + :ref:`rescontrol` sets up the restart parameters for a multiframe restart, enabling you to restart + an analysis from any load step and substep for which there is an :file:`.xnnn` file. You can perform + a multiframe restart for static and transient (full or mode-superposition method) analyses only. For + more information about multiframe restarts and descriptions of the contents of the files used, see + `Restarting an Analysis + `_ + + **Syntax** + + * Multiframe restart files are generically indicated here as :file:`.xnnn` files. They correspond to + :file:`.rnnn` files for nonlinear static and full transient analyses, and :file:`.mnnn` files for + mode-superposition analyses. + * Remeshing database files are indicated as :file:`.rdnn` files. This type of restart file is needed + only after remeshing during a `nonlinear mesh adaptivity + `_ analysis. + * When ``Action`` = DEFINE, the specified ``Filetype`` determines the type of file ( :file:`.xnnn` + or :file:`.rdnn` ) controlled by this command. + + **Number of Restart Files Allowed** + + * The total number of restart files for any analysis cannot exceed 999 (for example, + :file:`jobname.r001` to :file:`jobname.r999` ). + * The total number of remeshing database files cannot exceed 99 (for example, :file:`jobname.rd01` + to :file:`jobname.rd99` ). + + **Considerations for** `Nonlinear Mesh Adaptivity + `_ Analysis + + * To control both :file:`.xnnn` and :file:`.rdnn` file writing ( ``Filetype`` = XNNN and + ``Filetype`` = RDNN, respectively), separate :ref:`rescontrol` commands are necessary. + * ``Action`` = NORESTART and ``Ldstep`` = NONE are not valid and will cause the analysis to fail. + * ``Ldstep`` = ``-N`` is not valid for controlling :file:`.xnnn` files. + + **Limiting the Number of Files Saved** + + * If you have many substeps for each load step and are writing :file:`.xnnn` files frequently, you + may want to set ``MAXFILES`` to limit the number of :file:`.xnnn` files saved, as they can fill + your disk quickly. + * You can specify ``MAXFILES`` and ``Frequency`` for individual load steps. These arguments take on + the default value or the value defined by :ref:`rescontrol`,,ALL, ``Frequency``, ``MAXFILES`` if + they are not explicitly defined for a specific load step. + * When :file:`.xnnn` files are written over many load steps, you may want to further limit the + number of :file:`.xnnn` files by setting ``MAXTotalFiles``. + + **Maximum Number of Load Steps** + + * You can specify a maximum of ten load steps; that is, you can issue the :ref:`rescontrol`,,N + command a maximum of ten times. Specified load steps cannot be changed in a restart. + + **Specifying** ``Ldstep`` = LAST or ``-N`` + + * The program accepts only one occurrence of :ref:`rescontrol` with ``Ldstep`` = LAST. If you issue + :ref:`rescontrol`,,LAST, ``Frequency``, ``MAXFILES`` multiple times, the last specification + overwrites the previous one. + * The program accepts only one occurrence of :ref:`rescontrol` with a negative ``Ldstep`` value ( + :ref:`rescontrol`, ``N`` where ``N`` is a negative number). If you issue :ref:`rescontrol` + multiple times with a negative ``Ldstep`` value, the last specification overwrites the previous + one. + + **Using** :ref:`rescontrol` in a Restarted Analysis + + * The :ref:`rescontrol` command is not valid in the restarted load step of a restart analysis. It is + only valid in subsequent load steps. + + **Example Usage** + + * `Multiframe Restart + `_ + * `Linear Perturbation Analysis + `_ + """ + command = f"RESCONTROL,{action},{ldstep},{frequency},{maxfiles},,{maxtotalfiles},{filetype}" + return self.run(command, **kwargs) + + def rstcontrol( + self, + type_: str = "", + cname: str = "", + method: str = "", + methoditem: str = "", + **kwargs, + ): + r"""Controls whether element single value results are written to the results file. + + Mechanical APDL Command: `RSTCONTROL `_ + + Parameters + ---------- + type_ : str + Solution format for database and file-write control: + + * ``AUTO`` - Write element output quantities (STRS, EPEL, EPPL, EPCR, EPTH) in single value form for + those element types that support it, and in element nodal form for all other element types + (default). See `Element Single Value Results + `_ + + * ``ELSV`` - Write element output quantities only in single value form. If the single value form is + not supported by the element types in the model, none of the applicable results (STRS, EPEL, EPPL, + EPCR, EPTH) will be available. + + * ``ELND`` - Write all element output quantities only in element nodal form. + + * ``ERASE`` - Reset :ref:`rstcontrol` specifications to their default values. + + * ``STAT`` - List the current :ref:`rstcontrol` specifications. + + cname : str + Name of the component (created via :ref:`cm` ) defining the selected set of elements for which + this specification is active. If no name is entered, the specification applies to all elements. + + method : str + For single value results, ``Method`` controls how the integration point values of each element are reduced to one value: + + * ``AVG`` - Use a simple average of values from all integration points (default). + + * ``MAXE`` - Use only the integration point corresponding to the maximum equivalent (EQV) stress or + strain quantity specified by ``MethodItem``. + + * ``MAXP`` - Use only the integration point corresponding to the maximum 1st principal stress or + strain quantity specified by ``MethodItem``. + + * ``MAXS`` - Use only the integration point corresponding to the maximum shear stress or strain + quantity specified by ``MethodItem``. + + methoditem : str + The quantity used to determine the integration point where single value results are reported. Only + valid when ``Method`` = MAXE, MAXP, or MAXS. + + * ``STRS`` - Choose the integration point based on stress. + + * ``EPEL`` - Choose the integration point based on elastic strain. + + * ``EPPL`` - Choose the integration point based on plastic strain. + + * ``EPCR`` - Choose the integration point based on creep strain. + + * ``EPTH`` - Choose the integration point based on thermal strain. + + Notes + ----- + :ref:`rstcontrol` is an optional output control command that specifies whether element nodal results + or element single value results are written to the results file. This command works in conjunction + with the :ref:`outres` command. :ref:`outres` specifies when each element quantity will be output, + while :ref:`rstcontrol` specifies the type of result (element nodal versus single value). Not all + elements support single value results. For more information, see `Element Single Value Results + `_ + + The element output quantities affected by this command are: + + * stress (STRS) + * elastic strain (EPEL) + * plastic strain (EPPL) + * creep strain (EPCR) + * thermal/swelling strains (EPTH) + + You can issue up to 50 :ref:`rstcontrol` commands in an analysis. :ref:`rstcontrol`,ERASE erases the + existing output specifications and resets the counted number of :ref:`rstcontrol` commands to zero. + + :ref:`rstcontrol` is also valid in PREP7. + """ + command = f"RSTCONTROL,{type_},{cname},{method},{methoditem}" + return self.run(command, **kwargs) + + def sbclist(self, **kwargs): + r"""Lists solid model boundary conditions. + + Mechanical APDL Command: `SBCLIST `_ + + Notes + ----- + + .. _SBCLIST_notes: + + Lists all solid model boundary conditions for the selected solid model entities. See also + :ref:`dklist`, :ref:`dllist`, :ref:`dalist`, :ref:`fklist`, :ref:`sfllist`, :ref:`sfalist`, + :ref:`bfllist`, :ref:`bfalist`, :ref:`bfvlist`, and :ref:`bfklist` to list items separately. + + This command is valid in any processor. + """ + command = "SBCLIST" + return self.run(command, **kwargs) + + def sbctran(self, **kwargs): + r"""Transfers solid model loads and boundary conditions to the FE model. + + Mechanical APDL Command: `SBCTRAN `_ + + Notes + ----- + + .. _SBCTRAN_notes: + + Causes a manual transfer of solid model loads and boundary conditions to the finite element model. + Loads and boundary conditions on unselected keypoints, lines, areas, and volumes are not + transferred. Boundary conditions and loads will not be transferred to unselected nodes or elements. + The :ref:`sbctran` operation is also automatically done upon initiation of the solution calculations + ( :ref:`solve` ). + + This command is also valid in PREP7. + """ + command = "SBCTRAN" + return self.run(command, **kwargs) + + def wsprings(self, **kwargs): + r"""Creates weak springs on corner nodes of a bounding box of the currently selected elements. + + Mechanical APDL Command: `WSPRINGS `_ + + Notes + ----- + + .. _WSPRINGS_notes: + + This command invokes a predefined Mechanical APDL macro that is used during the import of loads from + the + ADAMS program into Mechanical APDL. + + The command creates weak springs on the corner nodes of the bounding box of the currently selected + elements. The six nodes of the bounding box are attached to ground using ``COMBIN14`` elements. The + stiffness is chosen as a small number and can be changed by changing the real constants of the + ``COMBIN14`` elements. + + The command works only for models that have a geometric extension in two or three dimensions. One- + dimensional problems (pure beam in one axis) are not supported. + + For more information about how :ref:`wsprings` is used during the transfer of loads from the ADAMS + program to Mechanical APDL, see `Import Loads into Mechanical APDL + `_. + + Distributed-Memory Parallel (DMP) Restriction This command is not supported in a DMP solution. + """ + command = "WSPRINGS" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/miscellaneous_loads.py b/src/ansys/mapdl/core/_commands/solution/miscellaneous_loads.py deleted file mode 100644 index 54552319ac4..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/miscellaneous_loads.py +++ /dev/null @@ -1,1469 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MiscellaneousLoads: - def anpres(self, nfram="", delay="", ncycl="", refframe="", **kwargs): - """Produces an animated sequence of the time-harmonic pressure variation - - APDL Command: ANPRES - of an engine-order excitation in a cyclic harmonic analysis. - - Parameters - ---------- - nfram - Number of frame captures per cycle. Defaults to 3 times the number - of sectors. - - delay - Time delay (seconds) during animation. Defaults to 0.1 seconds. - - ncycl - Number of animation cycles. Defaults to 5. - - refframe - Reference frame for the model rotation. - - 0 - Rotating reference frame (default). The model remains fixed in space and the - pressure revolve around the model. - - 1 - Stationary reference frame. The model rotates and the pressure locations remain - fixed in space. - - Notes - ----- - ANPRES invokes a macro which produces an animated sequence of the time- - harmonic applied pressure in the case of a mode-superposition harmonic - analysis (ANTYPE,HARMIC with CYCOPT,MSUP,ON). The engine-order - excitation must also have been specified (CYCFREQ,EO). While pressure - loads are not accepted as valid loading in a mode-superposition - analysis (they must be applied in the modal analysis and the modal load - vector applied in the mode-superposition analysis) you can apply them - for the purposes of this animation. - - For RefFrame = 1 (stationary reference frame), the rotational velocity - from the Linear Perturbation step, or the current OMEGA or CGOMGA - value, is used to determine the rotation direction about the cyclic - cylindrical axis, otherwise a positive rotation is assumed. - - You may use /HBC,,ON to hide overlapping pressure faces, and use - /GLINE,,-1 to suppress the element outlines if desired. - """ - command = f"ANPRES,{nfram},{delay},{ncycl},{refframe}" - return self.run(command, **kwargs) - - def aport( - self, - portnum="", - label="", - kcn="", - pres="", - phase="", - val1="", - val2="", - val3="", - val4="", - **kwargs, - ): - """Specifies input data for plane wave and acoustic duct ports. - - APDL Command: APORT - - Parameters - ---------- - portnum - Port number. This number is associated with an exterior port - or interior port previously specified by the SF and BF family - of commands, respectively. The number must be between 1 and - 50. - - Label - - * ``"PLAN"`` : Incident plane wave. - * ``"RECT"`` : Rectangular duct. - * ``"CIRC"`` : Circular duct. - * ``"COAX"`` : Coaxial duct. - * ``"LIST"`` : List the port settings. If PortNum = ALL, list the port settings for all defined ports. - * ``"DELE"`` : Delete defined ports. If PortNum = ALL, delete all defined ports. - - kcn - A previously-defined local (KCN >10) or global (KCN = 0) - Cartesian coordinate system number used to specify the - geometric properties of the duct. Defaults to the global - Cartesian coordinate system (0). The local Z-direction must be - the direction of wave propagation. The origin of the local - coordinate system must be centered about the face of the duct - port without considering symmetry. - - pres - Zero-to-peak amplitude of the pressure. If blank, the port - will appear as a matching impedance. - - phase - Phase angle of the applied pressure in degrees. Defaults to 0. - - VAL1, VAL2, VAL3, VAL4 - Additional input. The meaning of VAL1 through VAL4 varies - depending on the specified Label. If ``label="PLAN"``: - - * ``"VAL1"`` : angle from positive X-axis to positive Y-axis - in the local Cartesian coordinates (KCN). - - * ``"VAL2"`` : angle away from positive Z-axis in the local - Cartesian coordinates (KCN). - - if ``label="RECT"``: - - * ``"VAL1"`` : Width of the rectangular duct. - * ``"VAL2"`` : Height of the rectangular duct. - * ``"VAL3"`` : Mode index for pressure variation along the - width (defaults to 0). - * ``"VAL4"`` : Mode index for pressure variation along the - height (defaults to 0). - - if ``label="CIRC"``: - - * ``"VAL1"`` : Radius of the circular duct. - * ``"VAL2"`` : Not used. - * ``"VAL3"`` : Mode index for pressure variation along the - azimuth (defaults to 0). - * ``"VAL4"`` : Mode index for pressure variation along the - radii (defaults to 0). - - if ``label="COAX"``: - - * ``"VAL1"`` : Inner radius of the coaxial duct. - * ``"VAL2"`` : Outer radius of the coaxial duct. - * ``"VAL3"`` : Mode index for pressure variation along the - azimuth (defaults to 0). - * ``"VAL4"`` : Mode index for pressure variation along the - radii (defaults to 0). - - Notes - ----- - Use the APORT command to launch a specified analytic acoustic mode - into a guided duct. - - The low-order FLUID30 element does not support the higher modes in - the coaxial duct ``label="COAX"``. - - For more information, see Specified Mode Excitation in an Acoustic - Duct in the Acoustic Analysis Guide, and Analytic Port Modes in a - Duct in the Mechanical APDL Theory Reference. - """ - command = ( - f"APORT,{portnum},{label},{kcn},{pres},{phase},,{val1},{val2},{val3},{val4}" - ) - return self.run(command, **kwargs) - - def asifile( - self, - opt="", - fname="", - ext="", - oper="", - kdim="", - kout="", - limit="", - **kwargs, - ): - """Writes or reads one-way acoustic-structural coupling data. - - APDL Command: ASIFILE - - Parameters - ---------- - opt - Command behavior option: - - WRITE - Write the structural results to the specified file. - - READ - Read the structural results from the specified file. - - fname - File name and directory path of a one-way acoustic-structural - coupling data file (248 characters maximum, including the - characters needed for the directory path). An unspecified directory - path defaults to the working directory; in this case, you can use - all 248 characters for the file name (defaults to jobname). - - ext - File name extension of the one-way acoustic-structural coupling - data file (defaults to .asi). - - oper - Command operation: - - NOMAP - No mapping occurs between the structural and acoustic models when reading the - structural results from the specified file (default). - - MAP - Maps the results from the structural to the acoustic model. (See "Notes".) - - kdim - Interpolation criteria. Valid only when Oper = MAP. - - kout - Outside region results. Valid only when Oper = MAP. - - limit - Number of nearby nodes considered for interpolation. Valid only - when Oper = MAP. - - Notes - ----- - The ASIFILE command writes to, or reads from, a file containing one-way - acoustic-structural coupling data. - - Results data on the one-way coupling interface (defined by the - SF,,FSIN) in the structural model are written to the one-way coupling - result data file during the structural solution. - - One-way coupling results data are read into the acoustic model as the - velocity (harmonic) or acceleration (transient) excitation during the - sequential acoustic solution. - - If Oper = NOMAP, both structural and acoustic models must share the - same node number on the one-way coupling interface. - - If Oper = MAP: - - The one-way coupling interface must be defined in the acoustic model - (SF,,FSIN) such that it corresponds to the field-surface interface - number (FSIN) in the structural model. - - The output points are correct only if they are within the boundaries - set via the specified input points. - - Calculations for out-of-bound points require much more processing time - than do points that are within bounds. - - For each point in the acoustic destination mesh, the command searches - all possible triangles in the structural source mesh to find the best - triangle containing each point, then performs a linear interpolation - inside this triangle. For faster and more accurate results, consider - your interpolation method and search criteria carefully (see LIMIT). - - One-way coupling excitation can be applied to multiple frequencies or - time steps. - """ - command = f"ASIFILE,{opt},{fname},{ext},{oper},{kdim},{kout},{limit}" - return self.run(command, **kwargs) - - def awave( - self, - wavenum="", - wavetype="", - opt1="", - opt2="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", - val11="", - val12="", - val13="", - **kwargs, - ): - """Specifies input data for an acoustic incident wave. - - APDL Command: AWAVE - - Parameters - ---------- - wavenum - Wave number. You specify the integer number for an acoustic - incident wave inside or outside the model. The number must be - between 1 and 20. - - wavetype - Wave type: - - PLAN - Planar incident wave - - MONO - Monopole or pulsating sphere incident wave - - DIPO - Dipole incident wave - - BACK - Back enclosed loudspeaker - - BARE - Bare loudspeaker - - STATUS - Displays the status of the acoustic wave settings if Wavenum = a number between - 1 and 20 or ALL. - - DELE - Deletes the acoustic wave settings if Wavenum = a number between 1 and 20 or - ALL. - - opt1 - PRES - - PRES - Pressure - - VELO - Velocity - - opt2 - EXT - - EXT - Incident wave outside the model. - - INT - Incident wave inside the model. This option is only available for pure - scattered pressure formulation. - - val1, val2, val3, . . . , val13 - If Wavetype = PLAN, MONO, DIPO, BACK, or BARE: - - VAL1 - Amplitude of pressure or normal velocity to the sphere surface. - - VAL2 - Phase angle of the applied pressure or velocity (in degrees). Defaults to 0 - degrees. - - Notes - ----- - Use the ASOL command to activate the scattered field algorithm and the - ASCRES command for output control with the scattered field algorithm. - Refer to Acoustics in the Mechanical APDL Theory Reference for more - information about pure scattered field formulation. - """ - command = f"AWAVE,{wavenum},{wavetype},{opt1},{opt2},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10},{val11},{val12},{val13}" - return self.run(command, **kwargs) - - def biot(self, label="", **kwargs): - """Calculates the Biot-Savart source magnetic field intensity. - - APDL Command: BIOT - - Parameters - ---------- - label - Controls the Biot-Savart calculation: - - NEW - Calculate the magnetic source field intensity (Hs) from the selected set of - source elements to the selected set of nodes. Overwrite any - existing Hs field values. - - SUM - Calculate the Hs field from the selected set of source elements to the selected - set of nodes. Accumulate with any existing Hs field values. - - Notes - ----- - Calculates the Biot-Savart source magnetic field intensity (Hs) at the - selected nodes from the selected source elements. The calculation is - done at the time the BIOT command is issued. - - Source elements include primitives described by element SOURC36, and - coupled-field elements SOLID5, LINK68, and SOLID98. Current conduction - elements do not have a solved-for current distribution from which to - calculate a source field until after the first substep. Inclusion of a - current conduction element Hs field will require a subsequent BIOT,SUM - command (with SOURC36 elements unselected) and a SOLVE command. - - The units of Hs are as specified by the current EMUNIT command setting. - - This command is also valid in PREP7. - """ - command = f"BIOT,{label}" - return self.run(command, **kwargs) - - def dfswave( - self, - kcn="", - radius="", - psdref="", - dens="", - sonic="", - incang="", - npara="", - sampopt="", - **kwargs, - ): - """Specifies the incident planar waves with random phases for a diffuse - - APDL Command: DFSWAVE - sound field. - - Parameters - ---------- - kcn - Local coordinate system: - - N - Coordinate system number. Default = 0. - - DELETE - Delete defined incident diffused planar waves. - - radius - Radius of the reference sphere on which the incident planar waves - are distributed with equal energy. Defaults to 50 x the half- - maximum dimension of the structural panel. - - psdref - Reference power spectral density. Default = 1. - - dens - Mass density of incident planar wave media. Default = 2041 kg/m3. - - sonic - Sound speed in incident planar wave media. Default = 343.24 m/s) - - incang - Maximum incident angle (0o <= degree <= 180o) against the positive - z axis in the local coordinate system KCN. Default = 0o. - - npara - Number of divisions on the reference sphere with cutting planes - parallel to the x-y coordinate plane of the local coordinate - system. Default = 20. - - sampopt - Random sampling option: - - ALL - Initializes the random generator of incident planar wave phases and samples the - phases at each solving frequency. - - MULT - Initializes the random generator of incident planar wave phases at the first - frequency and samples the phases at each solving frequency. - - MONO - Initializes the random generator of incident planar wave phases and samples the - phases only once at first solving frequency so that the same - phases are used over the whole frequency range for each - incident planar wave. - - Notes - ----- - Issue the DFSWAVE command to activate a diffuse sound field. (The AWAVE - command does not activate a diffuse sound field.) - - The SURF154 surface element must be defined on the surface of the - structural solid element for the excitation. - - The acoustic elements and the absorbing boundary condition must be - defined in the open acoustic domain. Do not define the acoustic domain - on the excitation side. - - The PLST command calculates the average transmission loss for multiple - sampling phases at each frequency over the frequency range. - - The symmetry of a panel structure cannot be used to reduce the - simulation size, as the incident plane waves have varying random phase - angles. The z axis of the Cartesian coordinate system (KCN) must be - consistent with the panel’s outward normal unit vector at the center of - the panel’s sending side. - """ - command = ( - f"DFSWAVE,{kcn},{radius},{psdref},{dens},{sonic},{incang},{npara},{sampopt}" - ) - return self.run(command, **kwargs) - - def fluread( - self, fname="", ext="", kdim="", kout="", limit="", listopt="", **kwargs - ): - """Reads one-way Fluent-to-Mechanical APDL coupling data via a .cgns file - - APDL Command: FLUREAD - with one-side fast Fourier transformation complex pressure peak value. - - Parameters - ---------- - -- - Reserved. - - fname - File name and directory path of a one-way Fluent-to-Mechanical APDL - coupling data file (248 characters maximum, including the - characters needed for the directory path). An unspecified directory - path defaults to the working directory; in this case, you can use - all 248 characters for the file name. Defaults to jobname. - - ext - File name extension of the one-way Fluent-to-Mechanical APDL - coupling data file. Defaults to .cgns). - - kdim - Interpolation data for mapping. A value of 0 (default) or 2 applies - 2-D interpolation (where interpolation occurs on a surface). - - kout - Outside region results for mapping: - - 0 - Use the value(s) of the nearest region point for points outside of the region. - This behavior is the default. - - 1 - Set results extrapolated outside of the region to zero. - - limit - Number of nearby nodes considered for mapping interpolation. - Minimum = 5. Default = 20. - - listopt - Type of items picked: - - (blank) - No listing (default). - - SOURCE - List the node coordinates and complex pressure values on the Fluent source side - during the solution. - - TARGET - List the node coordinates and complex pressure values on the mapped Mechanical - APDL target side during the solution. - - BOTH - List the node coordinates and complex pressure values on both the Fluent source - side and the mapped Mechanical APDL target side during the - solution. - - Notes - ----- - The FLUREAD command reads one-way Fluent-to-Mechanical APDL coupling - data from a .cgns file. The Fluent one-side fast Fourier transformation - (FFT) peak complex pressure values are mapped to the Mechanical APDL - structure model during the acoustic-structural solution at each FFT - frequency. - - The command can be used only for the model with the acoustic elements. - - To apply complex pressure to the structure model, define the SURF154 - surface element, then define the one-way coupling interface (SF,,FSIN) - on the element. - - You can define the solving frequency range via the HARFRQ command. The - solver selects the FFT frequencies between the beginning and ending - frequencies. The number of substeps is determined by the number of FFT - frequencies over the frequency range. The number of substeps defined - via the NSUBST command is overwritten. - - For better mapping performance, consider the following: - - Calculations for out-of-bound points require much more processing time - than do points that are within bounds. - - For each point in the structural destination mesh, the command searches - all possible triangles in the Fluent source mesh to find the best - triangle containing each point, then performs a linear interpolation - inside this triangle. For faster and more accurate results, consider - your interpolation method and search criteria carefully. (See LIMIT.) - - It is possible to apply one-way coupling excitation to multiple - frequencies. The one-side FFT peak complex pressure values are - necessary to do so. - """ - command = f"FLUREAD,{fname},{ext},{kdim},{kout},{limit},{listopt}" - return self.run(command, **kwargs) - - def ic(self, node="", lab="", value="", value2="", nend="", ninc="", **kwargs): - """Specifies initial conditions at nodes. - - APDL Command: IC - - Parameters - ---------- - node - Node at which initial condition is to be specified. If ALL, apply - to all selected nodes (NSEL). If NODE = P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). A component name may be substituted for NODE. - - lab - Degree-of-freedom label for which the initial condition is to be - specified. If ALL, use all appropriate labels. - - value - Initial value of the degree of freedom (first-order value). - Defaults to the program default for that degree of freedom (0.0 for - structural analysis, TUNIF for thermal analysis, etc.). Values are - in the nodal coordinate system and in radians for rotational - degrees of freedom. - - value2 - Second-order degree of freedom value, mainly used to specify - initial structural velocity. Defaults to the program default for - that degree of freedom (0.0 for structural analysis). Values are - in the nodal coordinate system and in radians/time for rotational - degrees of freedom. - - nend, ninc - Specifies the same initial condition values at the range of nodes - from NODE to NEND (defaults to NODE), in steps of NINC (defaults to - 1). - - Notes - ----- - The IC command specifies initial conditions, which are the initial - values of the specified degrees of freedom. It is valid only for a - static analysis and full method transient analysis (TIMINT,ON and - TRNOPT,FULL). For the transient, the initial value is specified at the - beginning of the first load step, that is, at time = 0.0. - - Initial conditions should always be step applied (KBC,1) and not - ramped. - - If constraints (D, DSYM, etc.) and initial conditions are applied at - the same node, the constraint specification overrides. Exercise caution - when specifying constraints. The degree-of-freedom values start from - zero, or the first value given in the table when table name is - specified. To match the nonzero initial condition value with the - initial value for degree-of-freedom constraint, use a table for the - degree-of-freedom constraint. - - For thermal analyses, any TUNIF specification should be applied before - the IC command; otherwise, the TUNIF specification is ignored. If the - IC command is input before any TUNIF specification, use the ICDELE - command and then reissue any TUNIF specification and then follow with - the IC command. - - When issuing the IC command for elements SOLID278 Layered Thermal Solid - and SOLID279 Layered Thermal Solid with through-the-thickness degrees - of freedom (KEYOPT(3) = 2), layers are always interpolated linearly - based on the location of the degrees of freedom. - - Define consistent initial conditions. For example, if you define an - initial velocity at a single degree of freedom, the initial velocity at - every other degree of freedom will be 0.0, potentially leading to - conflicting initial conditions. In most cases, you should define - initial conditions at every unconstrained degree of freedom in your - model. If you define an initial condition for any degree of freedom at - the pilot node of a rigid body (see Modeling Rigid Bodies in the - Contact Technology Guide for the definition of rigid body), then the - same initial condition must also be defined for the same degree of - freedom on all other nodes of the rigid body. - - After a solution has been performed, the specified initial conditions - are overwritten by the actual solution and are no longer available. You - must respecify them if you want to perform a subsequent analysis. You - may want to keep a database file saved prior to the first solution for - subsequent reuse. - - If you use the CDWRITE command to archive your model, first-order - values (initial displacements, temperatures, etc.) specified via the IC - command are not written to the archive file; however, second-order - (structural velocity) terms are written. - - This command is also valid in PREP7. - """ - command = f"IC,{node},{lab},{value},{value2},{nend},{ninc}" - return self.run(command, **kwargs) - - def icdele(self, **kwargs): - """Deletes initial conditions at nodes. - - APDL Command: ICDELE - - Notes - ----- - Deletes all initial conditions previously specified with the IC command - at all nodes. - - This command is also valid in PREP7. - """ - command = f"ICDELE," - return self.run(command, **kwargs) - - def iclist(self, node1="", node2="", ninc="", lab="", **kwargs): - """Lists the initial conditions. - - APDL Command: ICLIST - - Parameters - ---------- - node1, node2, ninc - List initial conditions for nodes NODE1 to NODE2 (defaults to - NODE1) in steps of NINC (defaults to 1). If NODE1 = ALL (default), - NODE2 and NINC are ignored and initial conditions for all selected - nodes [NSEL] are listed. If NODE1 = P, graphical picking is - enabled and all remaining command fields are ignored (valid only in - the GUI). A component name may be substituted for NODE1 (NODE2 and - NINC are ignored). - - lab - Velocity key: - - DISP - Specification is for first order degree of freedom value (displacements, - temperature, etc.) (default). - - VELO - Specification is for second order degree of freedom value (velocities). - - Notes - ----- - Lists the initial conditions specified by the IC command. Listing - applies to all the selected nodes [NSEL] and DOF labels. ICLIST is not - the same as the DLIST command. All the initial conditions including - the default conditions are listed for the selected nodes. - - This command is valid in any processor. - """ - command = f"ICLIST,{node1},{node2},{ninc},{lab}" - return self.run(command, **kwargs) - - def icrotate( - self, - node="", - omega="", - x1="", - y1="", - z1="", - x2="", - y2="", - z2="", - vx="", - vy="", - vz="", - accel="", - **kwargs, - ): - """Specifies initial velocity at nodes as a sum of rotation about an axis and translation. - - APDL Command: ICROTATE - - Parameters - ---------- - NODE - Node at which the initial velocity is to be specified. If ALL, - apply to all selected nodes NSEL. A component name may be - input for NODE. - - OMEGA - Scalar rotational velocity about the rotational axis. - - X1, Y1, Z1 - Coordinates (in the global Cartesian coordinate system) of the - beginning point of the rotational axis vector. - - X2, Y2, Z2 - Coordinates (in the global Cartesian coordinate system) of the - end point of the rotational axis vector. - - Vx - Initial translational velocity in direction x of the nodal - coordinate system. - - Vy - Initial translational velocity in direction y of the nodal - coordinate system. - - Vz - Initial translational velocity in direction z of the nodal - coordinate system. - - accel - Key to initialize acceleration due to centrifugal effects: - - * ``""`` : (blank) Do not initialize acceleration (default). - * ``"CENT"`` : Initialize acceleration due to centrifugal - effects along with the initial velocity. - - Notes - ----- - The ICROTATE command specifies initial velocity for all - translational degrees of freedom of the specified nodes. The - velocity value is a combination of velocity due to rotation about - an axis and translation. - """ - command = f"ICROTATE,{node},{omega},{x1},{y1},{z1},{x2},{y2},{z2},{vx},{vy},{vz},{accel}" - return self.run(command, **kwargs) - - def mrpm(self, val1="", **kwargs): - """Defines the revolutions per minute (RPM) for a machine rotation. - - APDL Command: MRPM - - Parameters - ---------- - val1 - The RPM value (no default). - - Notes - ----- - A different RPM value can be defined at each load step. The RPM - value is used to postprocess the equivalent radiated power from - the structural surface (the PRAS and PLAS commands) or the - radiated sound power level (the PRFAR and PLFAR commands). - """ - return self.run(f"MRPM,{val1}", **kwargs) - - def outpr(self, item="", freq="", cname="", **kwargs): - """Controls the solution printout. - - APDL Command: OUTPR - - Parameters - ---------- - item - Item for print control: - - BASIC - Basic quantities (nodal DOF solution, nodal reaction loads, and element - solution) (default). - - NSOL - Nodal DOF solution. - - RSOL - Nodal reaction loads. - - ESOL - Element solution. - - NLOAD - Element nodal loads. When nonlinear stabilization is active, the stabilization - force/moments are also printed. - - SFOR - Stabilization force/moment at the applicable nodes (valid only when nonlinear - stabilization is active). - - VENG - Element energies. When nonlinear stabilization is active, the energy - dissipation due to stabilization is also printed. - - V - Nodal velocity (applicable to structural transient analysis only - (ANTYPE,TRANS)). - - A - Nodal acceleration (applicable to structural transient analysis only - (ANTYPE,TRANS)). - - ALL - All of the above solution items. - - freq - Print solution for this item every Freqth (and the last) substep of - each load step. If -n, print up to n equally spaced solutions - (only applies to static or full transient analyses when automatic - time stepping is enabled). If NONE, suppress all printout for this - item for this load step. If ALL, print solution for this item for - every substep. If LAST, print solution for this item only for the - last substep of each load step. For a modal analysis, use NONE or - ALL. - - cname - Name of the component, created with the CM command, defining the - selected set of nodes or elements for which this specification is - active. If blank, the set is all entities. - - Notes - ----- - Controls the solution items to be printed, the frequency with which - they are printed (in static, transient, or full harmonic analyses), and - the set of nodes or elements to which this specification applies (in - static, transient, or full harmonic analyses). An item is associated - with either a node (NSOL, RFORCE, V, and A items) or an element (all of - the remaining items). The specifications are processed in the order - that they are input. Up to 50 specifications (OUTPR and OUTRES - commands combined) may be defined. Use OUTPR,STAT to list the current - specifications and use OUTPR,ERASE to erase all the current - specifications. - - As described above, OUTPR writes some or all items (depending on - analysis type) for all elements. To restrict the solution printout, - use OUTPR to selectively suppress (Freq = NONE) the writing of solution - data, or first suppress the writing of all solution data - (OUTPR,ALL,NONE) and then selectively turn on the writing of solution - data with subsequent OUTPR commands. - - If the generalized plane strain feature is active and OUTPR is issued, - the change of fiber length at the ending point during deformation and - the rotation of the ending plane about X and Y during deformation will - be printed if any displacement at the nodes is printed. The reaction - forces at the ending point will be printed if any reaction force at the - nodes is printed. - - Nodal reaction loads (Item = RSOL) are processed according to the - specifications listed for the PRRSOL command. - - Result printouts for interactive sessions are suppressed for models - with more than 10 elements. - - This command is also valid in PREP7. - """ - command = f"OUTPR,{item},{freq},{cname}" - return self.run(command, **kwargs) - - def outres(self, item="", freq="", cname="", nsvar="", dsubres="", **kwargs): - """Controls the solution data written to the database. - - APDL Command: OUTRES - - Parameters - ---------- - item - Results item for database and file write control: - - ALL - All solution items except LOCI and SVAR. This behavior is the default. - - CINT - All available results generated by the CINT command - - ERASE - Resets OUTRES specifications to their default values. - - STAT - Lists the current OUTRES specifications. - - BASIC - Write only NSOL, RSOL, NLOAD, STRS, FGRAD, and FFLUX records to the results - file and database. - - NSOL - Nodal DOF solution. - - RSOL - Nodal reaction loads. - - V - Nodal velocity (applicable to structural full transient analysis only - (ANTYPE,TRANS)). - - A - Nodal acceleration (applicable to structural full transient analysis only - (ANTYPE,TRANS)). - - ESOL - Element solution (includes all items following): - - NLOAD - Element nodal, input constraint, and force loads (also used with the /POST1 - commands PRRFOR, NFORCE, and FSUM to calculate reaction - loads). - - STRS - Element nodal stresses. - - EPEL - Element elastic strains. - - EPTH - Element thermal, initial, and swelling strains. - - EPPL - Element plastic strains. - - EPCR - Element creep strains. - - EPDI - Element diffusion strains. - - FGRAD - Element nodal gradients. - - FFLUX - Element nodal fluxes. - - LOCI - Integration point locations. - - SVAR - State variables (used only by UserMat). - - MISC - Element miscellaneous data (SMISC and NMISC items of the ETABLE command). - - freq - Specifies how often (that is, at which substeps) to write the - specified solution results item. The following values are valid: - - cname - The name of the component, created with the CM command, defining - the selected set of elements or nodes for which this specification - is active. If blank, the set is all entities. A component name is - not allowed with the ALL, BASIC, or RSOL items. - - -- - Reserved for future use. - - nsvar - The number of user-defined state variables (TB,STATE) to be written - to the results file. Valid only when Item = SVAR and user-defined - state variables exist. The specified value cannot exceed the total - number of state variables defined; if no value is specified, all - user-defined state variables are written to the results file. This - argument acts on all sets of user-defined state variables that - exist for the model. - - dsubres - Specifies whether to write additional results in Jobname.DSUB - during a substructure or CMS use pass in transient or harmonic - analysis. - - Blank - Write the nodal DOF solution in Jobname.DSUB (default). - - ALL - In addition to the nodal DOF solution, also write necessary data to compute - quantities using nodal velocity and nodal acceleration - (damping force, inertial force, kinetic energy, etc.) in the - subsequent expansion pass. For more information, see Step 3: - Expansion Pass in the Substructuring Analysis Guide. - - Notes - ----- - The OUTRES command allows you to specify the following: - - The solution item (Item) to write to the database (and to the reduced - displacement and results files) - - The frequency (Freq) at which the solution item is written (applicable - to static, transient, or full harmonic analyses) - - The set of elements or nodes (Cname) to which your specification - applies. - """ - command = f"OUTRES,{item},{freq},{cname},{nsvar},{dsubres}" - return self.run(command, **kwargs) - - def osresult(self, item="", comp="", freq="", cname="", **kwargs): - """Controls the selected result data written to the database. - - APDL Command: OSRESULT - - Parameters - ---------- - item - Item to output to the database: - - ERASE - Erases all selected result output specifications - - STATUS - Lists the current set of selected result output specifications - - SVAR - State variable number - - FLD - User-defined field variables - - S - Component and derived (principal, intensity, equivalent) stresses - - EPEL - Component and derived (principal, intensity, equivalent) elastic strains - - EPPL - Component and derived (principal, intensity, equivalent) plastic strains - - EPCR - Component and derived (principal, intensity, equivalent) creep strains - - EPTH - Component and derived (principal, intensity, equivalent) thermal strains - - CDM - Mullins effect damage variable and maximum previous strain energy - - PMSV - Pore mechanics state variables for coupled pore-pressure-thermal elements - - FFLX - Fluid flow flux components in poromechanics - - FGRA - Fluid pore pressure gradient components in poromechanics - - BKS - Total nonlinear kinematic backstress components - - GDMG - Generalized and ductile damage values - - comp - Component of Item to output to the database: - - For S, EPEL, EPPL, EPCR, EPTH: X, Y, Z, XY, YZ, XZ, 1, 2, 3, INT, EQV - - For SVAR: 1, 2, 3, ..., N (state variable number) - - For FLD: UF01, UF02, ..., UF09 (user-defined field variables) - - For CDM: DMG, LM - - For PMSV: VRAT, PPRE, DSAT, RPER - - For FFLX, FGRA: X, Y, Z - - For BKS: X, Y, Z, XY, YZ, XZ - - For GDMG: ETA, ETAC, IDRA, DUCT (or blank for generalized damage) - - freq - Frequency to output to the database: - - n - Writes every nth and last substep of each load step - - -n - Writes up to n equally spaced substeps of each load step - - ALL - Writes every substep - - LAST - Writes the last substep of each load step (default) - - cname - The name of an element component (CM) defining the set of elements - for which this specification is active. If not specified, the set - is all elements. - - Notes - ----- - OSRESULT controls output to the results database for the selected result - defined by the item and component combination. The command activates output - of the selected result for the specified substeps and elements. Multiple - commands for the same result are cumulative. No selected results are written - to the database unless specified via OSRESULT. - - The saved selected quantities are accessible via standard postprocessing - commands (ANSOL, ETABLE, ESOL, PLESOL, PLNSOL, PRESOL, and PRNSOL). - - OSRESULT,ERASE deletes the existing output specifications. - - OSRESULT,STATUS lists the current set of selected result specifications. - - The output of selected results is valid for static (ANTYPE,STATIC) and - transient (ANTYPE,TRANS) analysis types. - - To select other results to output to the database, see OUTRES. (Element - quantities specified via OUTRES can be redundant to those specified via - OSRESULT. Avoid specifying redundant quantities, as they are stored and - processed separately.) - - All OSRESULT results are in the solution coordinate system. - - This command is also valid in PREP7. - - Examples - -------- - Enter solution - - >>> mapdl.slashsolu() - - Suppress all solution results output first - - >>> mapdl.outres("ALL", "NONE") - - Use OSRESULT to specify selected results - - >>> mapdl.osresult("S", "Y", "ALL") # Stress Y component - >>> mapdl.osresult("S", "EQV", "ALL") # Equivalent stress - >>> mapdl.osresult("EPPL", "INT", "ALL") # Plastic strain intensity - - Enter postprocessor - - >>> mapdl.post1() - - Retrieve selected results using PRESOL and PRNSOL - - >>> mapdl.presol("SRES", "SY") # Print selected stress Y - >>> mapdl.presol("SRES", "SEQV") # Print selected equivalent stress - >>> mapdl.prnsol("SRES", "EPPLINT") # Print selected plastic strain intensity - - """ - command = f"OSRESULT,{item},{comp},{freq},{cname}" - return self.run(command, **kwargs) - - def rescontrol( - self, - action="", - ldstep="", - frequency="", - maxfiles="", - maxtotalfiles="", - filetype="", - **kwargs, - ): - """Controls file writing for multiframe restarts. - - APDL Command: RESCONTROL - - Parameters - ---------- - action - Command action. Valid options are: - - DEFINE - Issuing the command specifies how frequently the ``.Xnnn`` restart files are - written for a load step (default). - - FILE_SUMMARY - Issuing the command prints the substep and load step information for all ``.Xnnn`` - files for the current jobname in the current - directory. If this option is specified, all other - arguments are ignored. - - STATUS - Issuing the command lists the current status in the tables of restart controls - specified previously by RESCONTROL. If this option is - specified, all other arguments are ignored. - - NORESTART - Issuing the command cleans up some of the restart files after a Distributed - ANSYS solution. The host process will not have the - following files in the working directory at the end of - the run: ``.ESAV``, ``.OSAV``, ``.Xnnn``, ```, `.LDHI``. The slave - processes will not have the following files in the - working directory at the end of the run: ``.ESAV``, ``.OSAV``, - ``.Xnnn``, ``.RST`` (or ``.RTH``, etc.). Some of the restart files - are never written, some are removed upon leaving ``/SOLU`` - (for example, upon FINISH), and some are removed upon - exiting the program. - - This option is useful for cleaning up files written by all of the Distributed - ANSYS processes, particularly when you know that these restart files will not - be needed later on. If this option is specified, all other arguments are ignored. - - If this option is used in shared-memory parallel ANSYS, most of the restart - files in the working directory are removed. It - has the same effect as issuing ``RESCONTROL,,NONE``. - - LINEAR - Issuing the command specifies the same actions as Action = DEFINE. However, - this option is intended for linear static applications. - For a linear static analysis, the restart capability is - normally not needed. However, it is typically needed when - a subsequent linear perturbation analysis is desired. By - default, none of the restart files are written for a - linear static analysis. - - DELETE - Delete the restart control specification corresponding to the ``Ldstep`` label on a - previous ``RESCONTROL,DEFINE`` command. - - ldstep - Specifies how the ``.Xnnn`` files are written for the specified load - steps. This option also affects how often the load history - information is written to the ``.LDHI`` file. - - ALL - Write the ``.Xnnn`` files at the same substep Frequency for all load steps; write - the load history information to the ``.LDHI`` file for all load - steps. - - LAST - Write the ``.Xnnn`` files for the last load step only; write load history - information to the ``.LDHI`` file for the last load step only. - This option is the default for nonlinear static and full - transient analyses. The remaining arguments are ignored. - - N - Number that indicates how often the ``.Xnnn`` file is written. - - Input a positive number to write the ``.Xnnn`` files at the substep ``Frequency`` - indicated only for load step N. - Other load steps will be written at the default substep frequency or at a frequency - defined by a previous ``RESCONTROL`` specification. - Load history information is written to the ``.LDHI`` file only for load steps N. - - Specifying a negative number (-N) to write the ``.Xnnn`` files for every Nth load step - at the specified substep Frequency. The load - history information is written to the ``.LDHI`` file - every Nth load step. This option is suitable for - restart applications in which more than a few - hundred load steps are required. Compared to the - ALL and positive N options, it can save disk - space since the ``.LDHI`` file is smaller and fewer - ``.Xnnn`` files are written. - - If Ldstep = -N, all other Ldstep options specified by ``RESCONTROL`` are - ignored and the program follows the -N option (write load history information every Nth load step). - If you want to change this pattern, issue ``RESCONTROL,DELETE, -N`` and then issue another - ``RESCONTROL`` command with the desired Ldstep option. - - NONE - No multiframe restart files (``.RDB`` [restart database file], ``.LDHI`` [load history file], - ``.Xnnn``) are created. This option is the default for mode-superposition analyses. - The remaining arguments are ignored. - - For nonlinear static, linear static, and full transient analyses, this option - allows a restart to be done at the last or abort - point using the same procedure as in ANSYS 5.5 or - earlier (using the ``.EMAT``, ``.ESAV`` or ``.OSAV``, and ``.DB`` - files). - - frequency - Frequency at which the ``.Xnnn`` files are written at the substep - level. - - NONE - Do not write any ``.Xnnn`` files for this load step. - - LAST - Write the ``.Xnnn`` files for the last substep of the load step only (default for - nonlinear static and full transient analyses). - - N - If ``N`` is positive, write the ``.Xnnn`` file every Nth substep of a load step. If ``N`` - is negative, write ``N`` equally spaced ``.Xnnn`` files within a load step. - - In nonlinear static and full transient analyses, negative ``N`` is valid only when ``AUTOTS,ON``. - In mode-superposition analyses, negative ``N`` is always valid. - - maxfiles - Maximum number of ``.Xnnn`` files to save for Ldstep. - - \\-1 - Overwrite existing ``.Xnnn`` files (default). The total maximum number of ``.Xnnn`` - files for one run is 999. If this number is reached before the analysis is complete, - the program will reset the ``.Xnnn`` file numbering back to 1 and continue to write - ``.Xnnn`` files; the program keeps the newest 999 restart files and overwrites the - oldest restart files. - - 0 - Do not overwrite any existing ``.Xnnn`` files. The total maximum number of ``.Xnnn`` - files for one run is 999. If this number is reached before the - analysis is complete, the analysis continues but no longer - writes any ``.Xnnn`` files. - - N - Maximum number of ``.xnnn`` files to keep for each load step. When ``N.xnnn`` files have - been written for a load step, the program overwrites the first ``.xnnn`` file of that load step - for subsequent substeps. - - .. warning:: ``N`` must be <= 999. If a total of 999 restart files is reached before - the analysis is complete, the analysis continues but writes no additional ``.xnnn`` files. - - maxtotalfiles - Total number of restart files to keep. ``Default = 999`` for ``.xnnn`` files and 99 for ``.rdnn`` files. This - option is valid only when ``MAXFILES`` = -1 (default). - Valid ``maxtotalfiles`` values are 1 through 999 for ``.xnnn`` files, and 1 through 99 for ``.rdnn`` files. - - When the total number of restart files written exceeds ``maxtotalfiles``, the program resets the - ``.xnnn`` or ``.rdnn`` file numbering back to 1 and continues to write ``.xnnn`` or ``.rdnn`` files. The - newest files are retained and the oldest files are overwritten. - - The ``maxtotalfiles`` value specified applies to all subsequent load steps. To reset it to the default, - reissue the command with ``maxtotalfiles`` = 0 or some negative value. - - If ``maxtotalfiles`` is set to different values at different load steps, and if the value of ``maxtotalfiles`` - specified in the prior load step is larger than that of the current load step, the program can - only overwrite the current number of maximum restart files up to the number ``maxtotalfiles`` - currently specified (which is smaller than the previous number). - - The recommended way to control the maximum number of restart files is to specify ``maxtotalfiles`` - at the first load step and not vary it in subsequent load steps. Also, ``maxtotalfiles`` is best used - when Ldstep = -N or ALL. - - filetype - The type of restart file to be controlled by this command. Valid only when Action = DEFINE: - - * **XNNN**: Control ``.xnnn`` files (default). - * **RDNN**: Control ``.rdnn`` remeshing database files. Needed only for a nonlinear mesh adaptivity analysis. - - Notes - ----- - - **COMMAND DEFAULT** - - If the ``RESCONTROL`` command is not issued during a structural analysis, the ``.RDB`` and ``.LDHI`` files are - written as described in Restarting an Analysis. - - **For nonlinear static and full transient analysis:** - - The default behavior is multiframe restart: ``RESCONTROL,DEFINE,LAST,LAST`` - The ``.xnnn`` file is written at the last substep of the last load step. An ``.rnnn`` file is also written at - the iteration prior to the abort point of the run if a ``jobname.abt`` file was used (or the **Stop** button - was pressed in the GUI), or if the job terminated because of a failure to reach convergence or some - other solution error. No information at the aborted substep is saved to the ``.xnnn`` file. - - **For nonlinear mesh adaptivity analysis:** - - The default behavior for ``.rdnn`` files written is: ``RESCONTROL,DEFINE,ALL,LAST,,,,RDNN`` - The ``.rdnn`` file is written at the last remesh of every load step by default. - The ``.rdnn`` and ``.rnnn`` files interact with each other. Generally, ``.rdnn`` file writing is superior to - that of ``.rnnn`` file writing. For example, if no RESCONTROL,DEFINE command is issued, the default - behavior is that both ``.rdnn`` and ``.rnnn`` files are written at the last occurrence of every load step - (equivalent to ``RESCONTROL,DEFINE,ALL,LAST`` and ``RESCONTROL,DEFINE,ALL,LAST,,,,RDNN``) - - - **NOTES** - - ``RESCONTROL`` sets up the restart parameters for a multiframe restart, enabling you to restart an analysis - from any load step and substep for which there is an ``.xnnn`` file. You can perform a multiframe restart - for static and transient (full or mode-superposition method) analyses only. For more information about - multiframe restarts and descriptions of the contents of the files used, see *Restarting an Analysis* in the - *Basic Analysis Guide*. - - **Syntax** - - Multiframe restart files are generically indicated here as ``.xnnn`` files. They correspond to .rnnn - files for nonlinear static and full transient analyses, and ``.mnnn`` files for mode-superposition - analyses. - Remeshing database files are indicated as ``.rdnn`` files. This type of restart file is needed only - after remeshing during a *nonlinear mesh adaptivity* analysis. - When ``Action = DEFINE``, the specified Filetype determines the type of file (``.xnnn`` or - ``.rdnn``) controlled by this command. - - **Number of Restart Files Allowed** - - The total number of restart files for any analysis cannot exceed 999 (for example, ``jobname.r001`` - to ``jobname.r999``). - The total number of remeshing database files cannot exceed 99 (for example, ``jobname.rd01`` - to ``jobname.rd99``). - - **Considerations for Nonlinear Mesh Adaptivity Analysis** - - To control both ``.xnnn`` and ``.rdnn`` file writing (``Filetype = XNNN`` and ``Filetype = RDNN``, - respectively), separate ``RESCONTROL`` commands are necessary. - ``Action = NORESTART`` and ``Ldstep = NONE`` are not valid and will cause the analysis to fail. - ``Ldstep = -N`` is not valid for controlling ``.xnnn`` files. - - **Limiting the Number of Files Saved** - - If you have many substeps for each load step and are writing ``.xnnn`` files frequently, you may - want to set ``maxfiles`` to limit the number of ``.xnnn`` files saved, as they can fill your disk - quickly. - You can specify ``maxfiles`` and ``Frequency`` for individual load steps. These arguments take - on the default value or the value defined by ``RESCONTROL,,ALL,Frequency,maxfiles`` if they - are not explicitly defined for a specific load step. - When ``.xnnn`` files are written over many load steps, you may want to further limit the number - of ``.xnnn`` files by setting ``maxtotalfiles``. - - **Maximum Number of Load Steps** - - You can specify a maximum of ten load steps; that is, you can issue the ``RESCONTROL,,N`` - command a maximum of ten times. Specified load steps cannot be changed in a restart. - - **Specifying Ldstep = LAST or Ldstep = -N** - - The program accepts only one occurrence of ``RESCONTROL`` with ``Ldstep = LAST``. If you issue - ``RESCONTROL,,LAST,Frequency,maxfiles`` multiple times, the last specification overwrites - the previous one. - The program accepts only one occurrence of ``RESCONTROL`` with a negative ``Ldstep`` value - (``RESCONTROL,,N`` where ``N`` is a negative number). If you issue ``RESCONTROL`` multiple times - with a negative ``Ldstep`` value, the last specification overwrites the previous one. - """ - command = f"RESCONTROL, {action}, {ldstep}, {frequency}, {maxfiles}, , {maxtotalfiles}, {filetype}" - return self.run(command, **kwargs) - - def sbclist(self, **kwargs): - """Lists solid model boundary conditions. - - APDL Command: SBCLIST - - Notes - ----- - Lists all solid model boundary conditions for the selected solid model - entities. See also DKLIST, DLLIST, DALIST, FKLIST, SFLLIST, SFALIST, - BFLLIST, BFALIST, BFVLIST, and BFKLIST to list items separately. - - This command is valid in any processor. - """ - command = f"SBCLIST," - return self.run(command, **kwargs) - - def sbctran(self, **kwargs): - """Transfers solid model loads and boundary conditions to the FE model. - - APDL Command: SBCTRAN - - Notes - ----- - Causes a manual transfer of solid model loads and boundary conditions - to the finite element model. Loads and boundary conditions on - unselected keypoints, lines, areas, and volumes are not transferred. - Boundary conditions and loads will not be transferred to unselected - nodes or elements. The SBCTRAN operation is also automatically done - upon initiation of the solution calculations [SOLVE]. - - This command is also valid in PREP7. - """ - command = f"SBCTRAN," - return self.run(command, **kwargs) - - def wsprings(self, **kwargs): - """Creates weak springs on corner nodes of a bounding box of the currently - - APDL Command: WSPRINGS - selected elements. - - Notes - ----- - WSPRINGS invokes a predefined ANSYS macro that is used during the - import of loads from the ADAMS program into the ANSYS program. WSPRINGS - creates weak springs on the corner nodes of the bounding box of the - currently selected elements. The six nodes of the bounding box are - attached to ground using COMBIN14 elements. The stiffness is chosen as - a small number and can be changed by changing the real constants of the - COMBIN14 elements. This command works only for models that have a - geometric extension in two or three dimensions. One dimensional - problems (pure beam in one axis) are not supported. - - For more information on how WSPRINGS is used during the transfer of - loads from the ADAMS program to ANSYS, see Import Loads into ANSYS in - the Substructuring Analysis Guide. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"WSPRINGS," - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_convergence_controls.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_convergence_controls.py deleted file mode 100644 index 263c209d936..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_convergence_controls.py +++ /dev/null @@ -1,140 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldConvergenceControls: - def mfconv(self, lab="", toler="", minref="", **kwargs): - """Sets convergence values for an ANSYS Multi-field solver analysis. - - APDL Command: MFCONV - - Parameters - ---------- - lab - Valid labels: - - toler - Convergence tolerance about program calculated reference value (the - L2 norm of the new load in a multi-field analysis). Defaults to - 0.01 (1%) for all labels. Must be less than 1.0. - - minref - The minimum value allowed for the program calculated reference - value. If negative, no minimum is enforced. Defaults to 1.0e-6 for - all labels. Not available in the GUI. MINREF corresponds to - ||ϕnew|| as defined in Set up Stagger Solution in the Coupled-Field - Analysis Guide. - - Notes - ----- - MFCONV sets convergence values for variables at the ANSYS - Multi-field solver interface. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide - for a list of all ANSYS Multi-field solver commands and their - availability for MFS and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported - in Distributed ANSYS. - """ - return self.run(f"MFCONV,{lab},{toler},,{minref}", **kwargs) - - def mfiter(self, maxiter="", miniter="", target="", **kwargs): - """Sets the number of stagger iterations for an ANSYS Multi-field solver - - APDL Command: MFITER - analysis. - - Parameters - ---------- - maxiter - Maximum number of iterations. Defaults to 10. - - miniter - Minimum number of iterations. Defaults to 1. - - target - Target number of iterations. Defaults to 5. - - Notes - ----- - The number of stagger iterations applies to each time step in an ANSYS - Multi-field solver analysis. MINITER and TARGET are valid only when - multi-field auto time stepping is on (MFDTIME). - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFITER,{maxiter},{miniter},{target}" - return self.run(command, **kwargs) - - def mfrelax(self, lab="", value="", option="", **kwargs): - """Sets relaxation values for an ANSYS Multi-field solver analysis. - - APDL Command: MFRELAX - - Parameters - ---------- - lab - Valid labels: - - value - Relaxation value. Defaults to 0.75 for all labels. - - option - Valid options are: - - RELX - Uses relaxation method for load transfer (default). - - LINT - Uses a linear interpolation for loaf transfer. - - Notes - ----- - MFRELAX sets relaxation values for the load transfer variables at a - surface or volume interface. Option = RELX will usually give you a more - stable and smooth load transfer and is suitable for strongly coupled - problems (such as FSI problems). Option = LINT is suitable for weakly - coupled problems because it will transfer the full load in fewer - stagger iterations. - - See the MFFR and MFITER commands for more information on relaxation in - the ANSYS Multi-field solver. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFRELAX,{lab},{value},{option}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_definition_commands.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_definition_commands.py deleted file mode 100644 index 7c984d82a7a..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_definition_commands.py +++ /dev/null @@ -1,237 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldSolverDefinitionCommands: - def mfcmmand(self, fnumb="", fname="", ext="", **kwargs): - """Captures field solution options in a command file. - - APDL Command: MFCMMAND - - Parameters - ---------- - fnumb - Field number specified by the MFELEM command. - - fname - Command file name specified for the field number. Defaults to field - "FNUMB". - - ext - Extension for Fname. Defaults to .cmd. - - Notes - ----- - All relevant solution option commands for the specified field are - written to a file with the extension .cmd. Refer to the commands in the - following tables in the Command Reference: Analysis Options, Nonlinear - Options, Dynamic Options, and Load Step Options. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFCMMAND,{fnumb},{fname},{ext}" - return self.run(command, **kwargs) - - def mfelem( - self, - fnumb="", - itype1="", - itype2="", - itype3="", - itype4="", - itype5="", - itype6="", - itype7="", - itype8="", - itype9="", - itype10="", - **kwargs, - ): - """Defines a field by grouping element types. - - APDL Command: MFELEM - - Parameters - ---------- - fnumb - Field number for a group of element types. - - itype1, itype2, itype3, . . . , itype10 - Element types defined by the ET command. - - Notes - ----- - You can define up to ten element types per field. - - Define only element types that contain elements in the field. Do not - include MESH200 because it is a "mesh-only" element that does not - contribute to the solution. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFELEM,{fnumb},{itype1},{itype2},{itype3},{itype4},{itype5},{itype6},{itype7},{itype8},{itype9},{itype10}" - return self.run(command, **kwargs) - - def mfem( - self, - fnumb="", - itype1="", - itype2="", - itype3="", - itype4="", - itype5="", - itype6="", - itype7="", - itype8="", - itype9="", - itype10="", - **kwargs, - ): - """Add more element types to a previously defined field number. - - APDL Command: MFEM - - Parameters - ---------- - fnumb - Existing field number defined by the MFELEM command. - - itype1, itype2, itype3, . . . , itype10 - Element types defined by the ET command. - - Notes - ----- - You can add up to ten element types per MFEM command. This command - should not be used after an initial solution. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFEM,{fnumb},{itype1},{itype2},{itype3},{itype4},{itype5},{itype6},{itype7},{itype8},{itype9},{itype10}" - return self.run(command, **kwargs) - - def mfexter( - self, - fnumb1="", - fnumb2="", - fnumb3="", - fnumb4="", - fnumb5="", - fnumb6="", - fnumb7="", - fnumb8="", - fnumb9="", - fnumb10="", - fnumb11="", - fnumb12="", - fnumb13="", - fnumb14="", - fnumb15="", - fnumb16="", - fnumb17="", - fnumb18="", - fnumb19="", - fnumb20="", - **kwargs, - ): - """Defines external fields for an ANSYS Multi-field solver analysis. - - APDL Command: MFEXTER - - Parameters - ---------- - fnumb1, fnumb2, fnumb3, . . . , fnumb20 - External field numbers defined by the MFELEM command. - - Notes - ----- - This command specifies external field numbers to be used for load - transfer in an ANSYS Multi-field solver analysis. Use the MFIMPORT - command to import the external fields. - - Use the MFELEM command to specify external field numbers. Use the - MFORDER command to specify the solution order for the external fields. - - You can define a maximum of 20 fields. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFEXTER,{fnumb1},{fnumb2},{fnumb3},{fnumb4},{fnumb5},{fnumb6},{fnumb7},{fnumb8},{fnumb9},{fnumb10},{fnumb11},{fnumb12},{fnumb13},{fnumb14},{fnumb15},{fnumb16},{fnumb17},{fnumb18},{fnumb19},{fnumb20}" - return self.run(command, **kwargs) - - def mffname(self, fnumb="", fname="", **kwargs): - """Specifies a file name for a field in an ANSYS Multi-field solver - - APDL Command: MFFNAME - analysis. - - Parameters - ---------- - fnumb - Field number specified by the MFELEM command. - - fname - File name. Defaults to field "FNUMB". - - Notes - ----- - All files created for the field will have this file name with the - appropriate extensions. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFFNAME,{fnumb},{fname}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_global_controls.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_global_controls.py deleted file mode 100644 index 23f2c06f0e2..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_global_controls.py +++ /dev/null @@ -1,372 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldSolverGlobalControls: - def mfanalysis(self, key="", **kwargs): - """Activates or deactivates an ANSYS Multi-field solver analysis. - - APDL Command: MFANALYSIS - - Parameters - ---------- - key - Multifield analysis key: - - ON - Activates an ANSYS Multi-field solver analysis. - - OFF - Deactivates an ANSYS Multi-field solver analysis (default). - - Notes - ----- - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFANALYSIS,{key}" - return self.run(command, **kwargs) - - def mfclear(self, option="", value="", **kwargs): - """Deletes ANSYS Multi-field solver analysis settings. - - APDL Command: MFCLEAR - - Parameters - ---------- - option - SOLU - - SOLU - Resets all ANSYS solution commands except KBC to their default states. This - option clears analysis options when setting up different - fields for an ANSYS Multi-field solver analysis. - - FIELD - Deletes all ANSYS Multi-field solver specifications for the specified field - number. - - SINT - Deletes all ANSYS Multi-field solver specifications for the specified surface - interface number. - - VINT - Deletes all ANSYS Multi-field solver specifications for the volumetric - interface number. - - ORD - Deletes the analysis order specified by the MFORDER command. - - EXT - Deletes external fields specified by the MFEXTER command - - MFLC - Deletes load transfers specified by the MFLCOMM command - - value - Use only for Option = FIELD, SINT, or VINT. - - Notes - ----- - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFCLEAR,{option},{value}" - return self.run(command, **kwargs) - - def mffr(self, fname="", lab="", rfini="", rfmin="", rfmax="", **kwargs): - """Setup Multi-Field relaxation factors for field solutions. - - APDL Command: MFFR - - Parameters - ---------- - fname - Field name (MFX) or number (MFS). Must be the ANSYS field (cannot - be a CFX field). - - lab - Label name. Valid values are DISP and TEMP. - - rfini - Initial relaxation factor. Defaults to 0.75. - - rfmin - Minimum relaxation factor. Defaults to RFINI. - - rfmax - Maximum relaxation factor. Defaults to RFINI. - - Notes - ----- - Use this command to relax the field solutions in fluid-solid - interaction analyses and thermal-thermal analyses for a better - convergence rate in coupled problems, especially cases that need - dynamic relaxation. The ANSYS field that has the MFFR command applied - will do only one nonlinear stagger iteration within each multi-field - stagger; the convergence of the ANSYS field solver will be satisfied - through multiple multi-field staggers. Note that the CFX field solver - can have multiple iterations within the field solver; see the CFX - documentation for more details. ANSYS will not terminate the nonlinear - field solution until the ANSYS field solver converges or reaches the - maximum number of multi-field staggers as specified on MFITER. - - The interface load relaxation (MFRELAX) will be automatically turned - off for the corresponding surface loads that have MFFR applied. The - automatic change of the relaxation factor for accelerating the - nonlinear convergence of the coupled field solution is based on - Aitken's acceleration scheme. - - This command is valid only with coupled problems involving surface load - transfer only. No subcycling is allowed for the field solver if using - this command. - """ - command = f"MFFR,{fname},{lab},{rfini},{rfmin},{rfmax}" - return self.run(command, **kwargs) - - def mfinter(self, option="", **kwargs): - """Specifies the interface load transfer interpolation option for an ANSYS - - APDL Command: MFINTER - Multi-field solver analysis. - - Parameters - ---------- - option - Interface load transfer option: - - CONS - Conservative formulation for load transfer. - - NONC - Nonconservative formulation for load transfer (default). - - Notes - ----- - This command only applies to the interpolation method for forces, heat - flux, and heat generation. Displacement and temperature transfers are - always nonconservative. - - For more information on conservative and nonconservative load transfer, - see Load Transfer in the Coupled-Field Analysis Guide. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFINTER,{option}" - return self.run(command, **kwargs) - - def mflist(self, option="", value="", **kwargs): - """Lists the settings for an ANSYS Multi-field solver analysis. - - APDL Command: MFLIST - - Parameters - ---------- - option - ALL - - ALL - Lists all ANSYS Multi-field solver analysis options. - - SOLU - Lists all solution-related ANSYS Multi-field solver options. - - FIELD - Lists all ANSYS Multi-field solver options related to the specified field - number. - - SINT - Lists all surface interface information for the specified surface interface - number. - - VINT - Lists all volumetric interface information for the specified volumetric - interface number. - - value - Use only for Option = FIELD, SINT, or VINT. - - Notes - ----- - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFLIST,{option},{value}" - return self.run(command, **kwargs) - - def mforder( - self, - fnumb1="", - fnumb2="", - fnumb3="", - fnumb4="", - fnumb5="", - fnumb6="", - fnumb7="", - fnumb8="", - fnumb9="", - fnumb10="", - fnumb11="", - fnumb12="", - fnumb13="", - fnumb14="", - fnumb15="", - fnumb16="", - fnumb17="", - fnumb18="", - fnumb19="", - fnumb20="", - **kwargs, - ): - """Specifies field solution order for an ANSYS Multi-field solver - - APDL Command: MFORDER - analysis. - - Parameters - ---------- - fnumb1, fnumb2, fnumb3, . . . , fnumb20 - Field numbers defined by the MFELEM command. - - Notes - ----- - You can define up to twenty fields in an ANSYS Multi-field solver - analysis. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFORDER,{fnumb1},{fnumb2},{fnumb3},{fnumb4},{fnumb5},{fnumb6},{fnumb7},{fnumb8},{fnumb9},{fnumb10},{fnumb11},{fnumb12},{fnumb13},{fnumb14},{fnumb15},{fnumb16},{fnumb17},{fnumb18},{fnumb19},{fnumb20}" - return self.run(command, **kwargs) - - def mfpsimul(self, gname="", fname1="", fname2="", **kwargs): - """Sets up a field solver group to simultaneously process with code - - APDL Command: MFPSIMUL - coupling analyses. - - Parameters - ---------- - gname - Sets the group name with a character string of up to 80 characters. - - fname1, fname2 - Sets the field solver 1 and field solver 2 names, which are - processed simultaneously, with a character string of up to 80 - characters. - - Notes - ----- - This command is used to define a group of simultaneously-processed - field solvers in an MFX analysis. For example, to define group g1 with - field solvers ansys-code and cfx-code, enter MFPS,g1,ansys-code,cfx- - code. - - To indicate groups of sequentially-processed field solvers for your MFX - analysis, create two groups (g1 and g2). - - A field solver refers to a specific instance of an ANSYS or CFX solver - execution that is defined by the respective input file(s) referenced - when starting the solver (through the launcher or from the command - line). The field solver names that are referenced in several MFX - commands must be consistent with the names that will be used when - starting the coupled simulation. - - Note:: : When running MFX from the launcher, you must use ANSYS and CFX - (uppercase) as the field solver names (MFPSIMUL) in your input file. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFPSIMUL,{gname},{fname1},{fname2}" - return self.run(command, **kwargs) - - def mfsorder(self, gname1="", gname2="", **kwargs): - """Sets up the solution sequence of simultaneous field solver groups for - - APDL Command: MFSORDER - code coupling analyses. - - Parameters - ---------- - gname1, gname2 - Specifies the group name for groups defined by the MFPSIMUL command - with a character string of up to 80 characters. - - Notes - ----- - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFSORDER,{gname1},{gname2}" - return self.run(command, **kwargs) - - def mfwrite(self, fname="", ext="", **kwargs): - """Writes an ANSYS master input file for MFX multiple code coupling. - - APDL Command: MFWRITE - - Parameters - ---------- - fname - File name and directory path (248 characters maximum, including the - characters needed for the directory path). An unspecified - directory path defaults to the working directory; in this case, you - can use all 248 characters for the file name. - - ext - Filename extension (eight-character maximum). - - Notes - ----- - When working interactively, you need to issue this command as the last - step in your setup process. This command will write out the input file - that you will then use to submit the MFX analysis. This file will - include the /SOLU, SOLVE, and FINISH commands. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - """ - command = f"MFWRITE,{fname},{ext}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_interface_mapping.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_interface_mapping.py deleted file mode 100644 index 3b13664bb13..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_interface_mapping.py +++ /dev/null @@ -1,222 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldSolverInterfaceMapping: - def mfbucket(self, key="", value="", **kwargs): - """Turns a bucket search on or off. - - APDL Command: MFBUCKET - - Parameters - ---------- - key - Bucket search key: - - ON - Activates a bucket search (default). - - OFF - Deactivates a bucket search. A global search is then activated. - - value - Scaling factor (%) used to determine the number of buckets for a - bucket search. Defaults to 50%. - - Notes - ----- - A bucket search will more efficiently compute the mapping of surface - and volumetric interpolation data across field interfaces (flagged by - the FSIN label using SF, SFA, SFE, or SFL or the FVIN label using BFE). - - The number of buckets used to partition a flagged interface is equal to - the scaling factor (%) times the total number of interface elements. - For example, for the default scaling factor of 50% and a 10,000 element - interface, 5,000 buckets are used. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFBUCKET,{key},{value}" - return self.run(command, **kwargs) - - def mfci(self, val1="", val2="", **kwargs): - """Sets the control parameters used by the conservative (CPP) - - APDL Command: MFCI - interpolation scheme. - - Parameters - ---------- - val1 - Controls the pixel resolution. The higher the resolution, the more - accurate and more expensive the conservative (CPP) interpolation - will be. Valid values are 10 to 256; defaults to 100. - - val2 - The separation factor to handle any gap between the two surfaces. - It is a relative measure of the gap, normalized by the averaged - element face sizes from both sides of the interface. Defaults to - 0.1. - - Notes - ----- - In a conservative (CPP) interpolation scheme as specified on the - MFLCOMM command, each element face is first divided into n number of - faces, where n is the number of nodes on the face. The three- - dimensional faces are then converted onto a two-dimensional polygon - made up of rows and columns of dots called pixels. By default, these - pixels have a resolution of 100 x 100; use VAL1 to increase the - resolution and improve the accuracy of the algorithm. See Load - Interpolation in the Coupled-Field Analysis Guide for more information - on interpolation schemes and adjusting the pixel resolution for the - conservative interpolation scheme. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFCI,{val1},{val2}" - return self.run(command, **kwargs) - - def mfmap(self, lab1="", lab2="", filename="", opt="", **kwargs): - """Calculates, saves, resumes, or deletes mapping data in an ANSYS Multi- - - APDL Command: MFMAP - field solver analysis. - - Parameters - ---------- - lab1 - Operation label: - - CALC - Calculate mapping data and keep it in memory (default). - - SAVE - Calculate mapping data, keep it in memory, and save it to a file. (If - MFMAP,CALC or MFMAP,RESU have been issued, just save it to - a file.) - - RESU - Resume the mapping from a file and keep it in memory. - - DELE - Free the mapping memory. - - lab2 - Applicable mapping label: - - ALL - Surface and volumetric mapping. - - SURF - Surface mapping only. - - VOLU - Volumetric mapping only. - - filename - The file name for a mapping data file (filename.sur for surface - mapping and filename.vol for volumetric mapping). Defaults to - Jobname. Applies to the commands MFMAP,SAVE and MFMAP,RESU only. - - opt - File format: - - BINA - Binary file (default). - - ASCI - ASCII file. - - Notes - ----- - This command calculates, saves, resumes, or deletes mapping data. It - defaults to calculating the mapping data. If MFMAP has not been - previously issued, the mapping data will be automatically calculated - during the solution process. On the other hand, the ANSYS Multi-field - solver will use previously created mapping data. Resumed mapping files - must have load transfer specifications that are consistent with those - of the current MFSURFACE and MFVOLUME commands and the ANSYS database. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFMAP,{lab1},{lab2},{filename},{opt}" - return self.run(command, **kwargs) - - def mftol(self, key="", value="", toler="", **kwargs): - """Activates or deactivates normal distance checking for surface mapping - - APDL Command: MFTOL - in an ANSYS Multi-field solver analysis. - - Parameters - ---------- - key - Normal distance key - - ON - Activates normal distance checking. - - OFF - Deactivates normal distance checking (default). - - value - The normal distance tolerance for surface mapping. Defaults to - 1.0e-6. If Toler = REL, Value is dimensionless. If Toler = ABS, - Value has the dimensions of length. - - toler - Tolerance definition key - - REL - Activates relative gap tolerance, which is independent of units (default). - - ABS - Activates absolute gap tolerance. - - Notes - ----- - For a dissimilar mesh interface, the nodes of one mesh are mapped to - the local coordinates of an element in the other mesh. When normal - distance checking is activated, the mapping tool checks the normal - distance from the node to the nearest element. The node is considered - improperly mapped if the normal distance exceeds the tolerance value. - The mapping tool creates a component to graphically display the - improperly mapped nodes. See Mapping Diagnostics in the Coupled-Field - Analysis Guide for more information. - - When using relative gap tolerance (Toler = REL), the normal distance - tolerance is derived from the product of the relative tolerance Value - and the largest dimension of the Cartesian bounding box for a specific - interface. Therefore, each interface will have a different normal - distance tolerance , even though MFTOL is a global command. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFTOL,{key},{value},{toler}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_load_transfer.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_load_transfer.py deleted file mode 100644 index 3f9ce0dc3b4..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_load_transfer.py +++ /dev/null @@ -1,236 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldSolverLoadTransfer: - def mflcomm( - self, - type_="", - fname1="", - intname1="", - label1="", - fname2="", - intname2="", - label2="", - option="", - **kwargs, - ): - """Defines a load transfer for code coupling analyses. - - APDL Command: MFLCOMM - - Parameters - ---------- - type\\_ - Set to SURF for a surface load transfer. Only surface load - transfers are available for MFX. - - fname1 - Sets the field solver name for the server (sending) code with a - case-sensitive character string of up to 80 characters. - - intname1 - Sets the interface name or number for the field solver of the - server code. ANSYS interfaces are numbered and are defined by the - SF family of commands (SF, SFA, or SFE) with the FSIN surface load - label. CFX interfaces use names, which are set in CFX-Pre. - - label1 - Sets the surface load label for the field solver of the server code - with a character string of up to 80 characters. ANSYS uses a - combination of the label and option to determine what data is - transferred (e.g., heat flows and not fluxes are sent with the - label/option pair HFLU/CPP). ANSYS cannot serve total force or - total force density to CFX for either formulation. CFX will send - the data requested by the label regardless of the option. CFX - labels that have more than one word must be enclosed in single - quotes. Note that this field is case-sensitive; i.e., FORC will - work, but forc will not. - - fname2 - Sets the field solver name for the client (receiving) code with a - character string of up to 80 characters. - - intname2 - Sets the interface name or number for the field solver of the - client code with a character string of up to 80 characters. ANSYS - interfaces are numbered and are defined by the SF family of - commands (SF, SFA, or SFE) with the FSIN surface load label. CFX - interfaces use names, which are set in CFX-Pre. - - label2 - Sets the surface load label for the field solver of the client code - with a character string of up to 80 characters. ANSYS uses a - combination of the label and option to determine what data is - transferred (e.g., heat flows and not fluxes are sent with the - label-option pair HFLU/CPP). CFX will send the data requested by - the label regardless of the option. CFX labels that have more than - one word must be enclosed in single quotes. Note that this field is - case-sensitive; i.e., FORC will work, but forc will not. - - option - NONC - - NONC - Profile preserving: Sets the interface load transfer to the nonconservative - formulation (default for displacement and temperature). In - the nonconservative formulation, the force density (or heat - flux) is transferred across the interface, preserving the - density profile between the two fields. - - CPP - Conservative: Uses a local conservative formulation while preserving the - density profile (default for total force and wall heat flow). - In the conservative formulation, total force (or heat flow) - must be transferred across the interface from the CFX field - solver to the ANSYS field solver. - - Notes - ----- - ANSYS input should always be in consistent units for its model. - - ANSYS uses a combination of the label and option to determine what data - to transfer. CFX will send exactly the data requested by the label, - regardless of the option. However, for the NONC option, the CFX label - must be Total Force Density or Wall Heat Flux and for the CPP option, - the CFX label must be Total Force or Wall Heat Flow. - - For more information on profile preserving and conservative load - transfer, see Load Interpolation in the Coupled-Field Analysis Guide. - Mapping Diagnostics are also available; however, if the improperly- - mapped nodes are based on the CFX mesh, you should ignore the ANSYS- - generated components because the CFX nodes are not present in the ANSYS - database. - - If you are working interactively, you can choose two pre-defined - combinations, Mechanical or Thermal, or you can choose a Custom option. - If you choose the Mechanical load type, then the Total Force Density - and Total Mesh Displacement data (corresponding to the ANSYS FORC and - DISP labels, respectively) is transferred. If you choose the Thermal - load type, then the Temperature and Wall Heat Flux data (corresponding - to the ANSYS TEMP and HFLU labels, respectively) is transferred. If you - choose Custom, you can select any valid combination of label and option - as described above. - - The ANSYS Multi-field solver solver does not allow you to switch the - load transfer direction for the same load quantity across the same - interfaces for a restart run. For example, if Field1 sends temperature - to and receives heat flow from Field2 across Interface 1 in a previous - solution, then you cannot make Field1 send heat flow to and receive - temperatures from Field2 across the same interface in a restart run, - even if you cleared the corresponding load transfer command. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFLCOMM,{type_},{fname1},{intname1},{label1},{fname2},{intname2},{label2},{option}" - return self.run(command, **kwargs) - - def mfsurface(self, inumb="", fnumb1="", label="", fnumb2="", **kwargs): - """Defines a surface load transfer for an ANSYS Multi-field solver - - APDL Command: MFSURFACE - analysis. - - Parameters - ---------- - inumb - Interface number for load transfer. The interface number - corresponds to the interface number specified by the surface flag - FSIN (SFxxcommands). - - fnumb1 - Field number of sending field. - - label - Valid surface load labels: - - fnumb2 - Field number for receiving field. - - Notes - ----- - This command is also valid in PREP7. - - The ANSYS Multi-field solver solver does not allow you to switch the - load transfer direction for the same load quantity across the same - interfaces for a restart run. For example, if Field1 sends temperature - to and receives heat flow from Field2 across Interface 1 in a previous - solution, then you cannot make Field1 send heat flow to and receive - temperatures from Field2 across the same interface in a restart run, - even if you cleared the corresponding load transfer command. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFSURFACE,{inumb},{fnumb1},{label},{fnumb2}" - return self.run(command, **kwargs) - - def mfvolume(self, inumb="", fnumb1="", label="", fnumb2="", **kwargs): - """Defines a volume load transfer for an ANSYS Multi-field solver - - APDL Command: MFVOLUME - analysis. - - Parameters - ---------- - inumb - Interface number for load transfer. The interface number - corresponds to the interface number specified by the volume flag - FVIN (BFE command). - - fnumb1 - Field number of sending field. - - label - Valid volume load labels: - - fnumb2 - Field number for receiving field. - - Notes - ----- - This command is also valid in PREP7. - - The ANSYS Multi-field solver solver does not allow you to switch the - load transfer direction for the same load quantity across the same - interfaces for a restart run. For example, if Field1 sends temperature - to and receives heat flow from Field2 across Interface 1 in a previous - solution, then you cannot make Field1 send heat flow to and receive - temperatures from Field2 across the same interface in a restart run, - even if you cleared the corresponding load transfer command. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFVOLUME,{inumb},{fnumb1},{label},{fnumb2}" - return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_time_controls.py b/src/ansys/mapdl/core/_commands/solution/multi_field_solver_time_controls.py deleted file mode 100644 index a97645aa2c1..00000000000 --- a/src/ansys/mapdl/core/_commands/solution/multi_field_solver_time_controls.py +++ /dev/null @@ -1,233 +0,0 @@ -# Copyright (C) 2016 - 2025 ANSYS, Inc. and/or its affiliates. -# SPDX-License-Identifier: MIT -# -# -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files (the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions: -# -# The above copyright notice and this permission notice shall be included in all -# copies or substantial portions of the Software. -# -# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -# SOFTWARE. - - -class MultiFieldSolverTimeControls: - def mfcalc(self, fnumb="", freq="", **kwargs): - """Specifies a calculation frequency for a field in an ANSYS Multi-field - - APDL Command: MFCALC - solver analysis. - - Parameters - ---------- - fnumb - Field number set by the MFELEM command. - - freq - Perform calculation every Nth ANSYS Multi-field solver time step. - Defaults to 1 for every time step. - - Notes - ----- - This command only applies to a harmonic analysis of the specified - field. It is useful when a field contributes negligible field - interaction within a single ANSYS Multi-field solver time step. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFCALC,{fnumb},{freq}" - return self.run(command, **kwargs) - - def mfdtime(self, dtime="", dtmin="", dtmax="", carry="", **kwargs): - """Sets time step sizes for an ANSYS Multi-field solver analysis. - - APDL Command: MFDTIME - - Parameters - ---------- - dtime - Multi-field time step size. If automatic time stepping is being - used [see Notes below], DTIME is the starting time step. - - dtmin - Minimum time step. Defaults to DTIME. - - dtmax - Maximum time step. Defaults to DTIME. - - carry - Time step carryover key. - - OFF - Use DTIME as the starting time step for the next restart run (default). - - ON - Use the final time step from the previous run as the starting time step for the - next restart run. - - Notes - ----- - This command specifies time step sizes for an ANSYS Multi-field solver - analysis. If either DTMIN or DTMAX is not equal to DTIME, auto time- - stepping is turned on for the multi-field loop. ANSYS will - automatically adjust the time step size for the next multi-field step - between DTMIN and DTMAX, based on the status of the current - convergence, the number of target stagger iterations (specified by - MFITER), and the actual number of iterations needed to reach - convergence at the current time step. - - If auto time-stepping is turned off, the time step size must be evenly - divisible into the end time (specified by MFTIME) minus the start time - (0 for a new analysis or a restart time specified by MFRSTART). - - You can use a smaller time step within each ANSYS field analysis. This - is called subcycling. Use the DELTIM and AUTOTS commands to subcycle a - structural, thermal, or electromagnetic analysis. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFDTIME,{dtime},{dtmin},{dtmax},{carry}" - return self.run(command, **kwargs) - - def mfoutput(self, freq="", **kwargs): - """Specifies results file output frequency for an ANSYS - - APDL Command: MFOUTPUT - Multi-field solver analysis. - - Parameters - ---------- - freq - N - - N - Write solution every Nth (and the last) time - step. Defaults to 1, for every time step. - - -N - Writes up to -N equally spaced results (for multifield auto time stepping). - - NONE - Suppresses writing of results for all multifield time steps. - - ALL - Writes results for every multifield time step (default). - - LAST - Writes results for only the last multifield time step. - - %array% - Where %array% is the name of an n X 1 X 1 - dimensional array parameter defining n key - times, the data for the specified solution - results item is written at those key times. Key - times in the array parameter must appear in - ascending order. Value must be greater than or - equal to the ending time values for the load - step. - - For restart runs (see MFRSTART command), either change the - parameter values to fall between the beginning and ending - time values of the load step, or erase the current - settings and reissue the command with a new array - parameter. - For more information about defining array - parameters, see the ``*DIM`` command documentation. - - Notes - ----- - A MFOUTPUT setting overrides any other output frequency setting - (OUTRES). To select the solution items, use the OUTRES command. - - For the case of Freq = -n and Freq = %array%, the results at the time - points which first time reaches or exceeds the targeting ouptupt time - points will be written. - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFOUTPUT,{freq}" - return self.run(command, **kwargs) - - def mfrstart(self, time="", **kwargs): - """Specifies restart status for an ANSYS Multi-field solver analysis. - - APDL Command: MFRSTART - - Parameters - ---------- - time - Restart time - - 0 - New analysis (Default) - - -1 - Restart from the last result set from a previous run. - - n - Specify any positive number for the actual time point from which the ANSYS - Multi-field solver will restart. ANSYS checks the availability - of the result set and database file. - - Notes - ----- - For MFX analyses, ANSYS always passes an actual time value to CFX (zero - for a new analysis or a positive value for a restart run) and CFX - verifies the consistency with the initial results file. For more - details about ANSYS restart capabilities, please see Restarting an - Analysis in the Basic Analysis Guide. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFRSTART,{time}" - return self.run(command, **kwargs) - - def mftime(self, time="", **kwargs): - """Sets end time for an ANSYS Multi-field solver analysis. - - APDL Command: MFTIME - - Parameters - ---------- - time - End time of an ANSYS Multi-field solver analysis. Defaults to 1. - - Notes - ----- - A MFTIME setting overrides any other end time setting (TIME). - - This command is also valid in PREP7. - - See Multi-field Commands in the Coupled-Field Analysis Guide for a list - of all ANSYS Multi-field solver commands and their availability for MFS - and MFX analyses. - - Distributed ANSYS Restriction: This command is not supported in - Distributed ANSYS. - """ - command = f"MFTIME,{time}" - 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 index d990be3a8f8..40be7f18350 100644 --- a/src/ansys/mapdl/core/_commands/solution/nonlinear_options.py +++ b/src/ansys/mapdl/core/_commands/solution/nonlinear_options.py @@ -21,461 +21,562 @@ # SOFTWARE. -class NonLinearOptions: - def arclen(self, key="", maxarc="", minarc="", **kwargs): - """Activates the arc-length method. +class NonlinearOptions: - APDL Command: ARCLEN + def arclen(self, key: str = "", maxarc: str = "", minarc: str = "", **kwargs): + r"""Activates the arc-length method. + + Mechanical APDL Command: `ARCLEN `_ Parameters ---------- - key + key : str Arc-length key: - OFF - Do not use the arc-length method (default). + * ``OFF`` - Do not use the arc-length method (default). - ON - Use the arc-length method. + * ``ON`` - Use the arc-length method. - maxarc - Maximum multiplier of the reference arc-length radius (default = - 25). + maxarc : str + Maximum multiplier of the reference arc-length radius (default = 25). - minarc - Minimum multiplier of the reference arc-length radius (default = - 1/1000). + minarc : str + Minimum multiplier of the reference arc-length radius (default = 1/1000). Notes ----- - Activates the arc-length method and sets the minimum and maximum - multipliers for controlling the arc-length radius based on the initial - arc-length radius. - The initial arc-length radius, t0, is proportional (in absolute value) - to the initial load factor. The initial load factor is given by: + .. _ARCLEN_notes: - Initial Load Factor = TIME / NSBSTP + Activates the arc-length method and sets the minimum and maximum multipliers for controlling the + arc-length radius based on the initial arc-length radius. - where TIME is the time specified by the TIME command for the arc-length - load step, and NSBSTP is the number of substeps specified by the NSUBST - command. + The initial arc-length radius, t:sub:`0`, is proportional (in absolute value) to the initial load + factor. The initial load factor is given by: + + Initial Load Factor = ``TIME`` / ``NSBSTP`` + + where ``TIME`` is the time specified by the :ref:`time` command for the arc-length load step, and + ``NSBSTP`` is the number of substeps specified by the :ref:`nsubst` command. + + The factors ``MAXARC`` and ``MINARC`` are used to define the range for the arc-length radius to + expand and shrink during the substep solution: + + * t :sub:`MAX` = ``MAXARC`` \* t :sub:`0` + * t :sub:`MIN` = ``MINARC`` \* t :sub:`0` - The factors MAXARC and MINARC are used to define the range for the arc- - length radius to expand and shrink during the substep solution: - - In each substep, the arc-length radius is kept constant throughout the - equilibrium iterations. After each converged substep, the arc-length - radius for the next substep is modified depending on the convergence - behavior. If the substep converges and the program heuristic predicts - an easy convergence, the arc-length radius is enlarged. If the enlarged - value is greater than tMAX, the arc-length radius is reset to tMAX. If - the substep does not converge, bisection will take place until the arc- - length radius is reduced to tMIN. If further nonconvergence is + In each substep, the arc-length radius is kept constant throughout the equilibrium iterations. After + each converged substep, the arc-length radius for the next substep is modified depending on the + convergence behavior. If the substep converges and the program heuristic predicts an easy + convergence, the arc-length radius is enlarged. If the enlarged value is greater than t:sub:`MAX`, + the arc-length radius is reset to t:sub:`MAX`. If the substep does not converge, bisection will + take place until the arc-length radius is reduced to t:sub:`MIN`. If further nonconvergence is encountered, the solution terminates. - The arc-length method predicts the next time increment (that is, load - factor increment). Therefore, the AUTOTS and PRED commands are ignored - when the arc-length method is used. + The arc-length method predicts the next time increment (that is, load factor increment). Therefore, + the :ref:`autots` and :ref:`pred` commands are ignored when the arc-length method is used. - The STABILIZE and LNSRCH commands are also ignored. + The :ref:`stabilize` and :ref:`lnsrch` commands are also ignored. The arc-length method cannot be used in a multiframe restart. - For difficult problems, one suggestion is to increase the initial - number of substeps (NSUBST), and to prevent the arc-length radius from - increasing too rapidly (MAXARC = 1). + For difficult problems, one suggestion is to increase the initial number of substeps ( :ref:`nsubst` + ), and to prevent the arc-length radius from increasing too rapidly ( ``MAXARC`` = 1). - ARCLEN cannot be used for any load step that has no applied load or - displacement. + :ref:`arclen` cannot be used for any load step that has no applied load or displacement. - The arc-length method does not support tabular loads. In order to use - the arc-length method, you must replace tabular loads by other load - types and then run the analysis again. + The arc-length method does not support tabular loads. In order to use the arc-length method, you + must replace tabular loads by other load types and then run the analysis again. + + The arc-length method can only be used with the sparse solver ( :ref:`eqslv`,SPARSE). If any other + solver is specified, the solver method is automatically changed to sparse, and a warning message is + issued to notify you. """ command = f"ARCLEN,{key},{maxarc},{minarc}" return self.run(command, **kwargs) - def arctrm(self, lab="", val="", node="", dof="", **kwargs): - """Controls termination of the solution when the arc-length method is + def arctrm( + self, lab: str = "", val: str = "", node: str = "", dof: str = "", **kwargs + ): + r"""Controls termination of the solution when the arc-length method is used. - APDL Command: ARCTRM - used. + Mechanical APDL Command: `ARCTRM `_ Parameters ---------- - lab + lab : str Specifies the basis of solution termination: - OFF - Does not use ARCTRM to terminate analysis (default). + * ``OFF`` - Does not use :ref:`arctrm` to terminate analysis (default). - L - Terminates the analysis if the first limit point has been reached. The first - limit point is that point in the response history when the - tangent stiffness matrix becomes singular (i.e., the point at - which the structure becomes unstable). If Lab = L, arguments - VAL, NODE, DOF are ignored. + * ``L`` - Terminates the analysis if the first limit point has been reached. The first limit point + is that point in the response history when the tangent stiffness matrix becomes singular (that is, + the point at which the structure becomes unstable). If ``Lab`` = L, arguments ``VAL``, ``NODE``, + ``DOF`` are ignored. - U - Terminates the analysis when the displacement first equals or exceeds the - maximum desired value. + * ``U`` - Terminates the analysis when the displacement first equals or exceeds the maximum desired + value. - val - Maximum desired displacement (absolute value). Valid only if Lab = - U. The analysis terminates whenever the calculated displacement - first equals or exceeds this value. For rotational degrees of - freedom, VAL must be in radians (not degrees). + val : str + Maximum desired displacement (absolute value). Valid only if ``Lab`` = U. The analysis + terminates whenever the calculated displacement first equals or exceeds this value. For + rotational degrees of freedom, ``VAL`` must be in radians (not degrees). - node - Node number corresponding to displacement used to compare with - displacement specified by VAL. If blank, the maximum displacement - will be used. Valid only if Lab = U. + node : str + Node number corresponding to displacement used to compare with displacement specified by + ``VAL``. If blank, the maximum displacement will be used. Valid only if ``Lab`` = U. - dof - Valid degree of freedom label for nodal displacement specified by - NODE. Valid labels are UX, UY, UZ, ROTX, ROTY, ROTZ. Valid only - if NODE>0 and Lab = U. + dof : str + Valid degree of freedom label for nodal displacement specified by ``NODE``. Valid labels are UX, + UY, UZ, ROTX, ROTY, ROTZ. Valid only if ``NODE`` >0 and ``Lab`` = U. Notes ----- - The ARCTRM command is valid only when the arc-length method (ARCLEN,ON) - is used. - It can be convenient to use this command to terminate the analysis when - the first limit point is reached. In addition, the NCNV command should - be used to limit the maximum number of iterations. If the ARCTRM - command is not used, and the applied load is so large that the solution - path can never reach that load, the arc-length solution will continue - to run until a CPU time limit or a "maximum number of iterations" is - reached. + .. _ARCTRM_notes: + + The :ref:`arctrm` command is valid only when the arc-length method ( :ref:`arclen`,ON) is used. + + It can be convenient to use this command to terminate the analysis when the first limit point is + reached. In addition, the :ref:`ncnv` command should be used to limit the maximum number of + iterations. If the :ref:`arctrm` command is not used, and the applied load is so large that the + solution path can never reach that load, the arc-length solution will continue to run until a CPU + time limit or a "maximum number of iterations" is reached. """ command = f"ARCTRM,{lab},{val},{node},{dof}" return self.run(command, **kwargs) - def bucopt(self, method="", nmode="", shift="", ldmulte="", rangekey="", **kwargs): - """Specifies buckling analysis options. + def bucopt( + self, + method: str = "", + nmode: str = "", + shift: str = "", + ldmulte: str = "", + rangekey: str = "", + **kwargs, + ): + r"""Specifies buckling analysis options. - APDL Command: BUCOPT + Mechanical APDL Command: `BUCOPT `_ Parameters ---------- - method + method : str Mode extraction method to be used for the buckling analysis: - LANB - Block Lanczos + * ``LANB`` - Block Lanczos + + * ``SUBSP`` - Subspace iteration + + See `Eigenvalue and Eigenvector Extraction + `_ + + nmode : str + Number of buckling modes (that is, eigenvalues or load multipliers) to extract (defaults to 1). + + shift : str + By default, this value acts as the initial shift point about which the buckling modes are + calculated (defaults to 0.0). - SUBSP - Subspace iteration + When ``RangeKey`` = RANGE, this value acts as the lower bound of the load multiplier range of + interest ( ``LDMULTE`` is the upper bound). - nmode - Number of buckling modes (i.e., eigenvalues or load multipliers) to - extract (defaults to 1). + ldmulte : str + Boundary for the load multiplier range of interest (defaults to :math:`equation not available` + ). - shift - By default, this value acts as the initial shift point about which - the buckling modes are calculated (defaults to 0.0). + When ``RangeKey`` = CENTER, the ``LDMULTE`` value determines the lower and upper bounds of the + load multiplier range of interest (- ``LDMULTE``, + ``LDMULTE`` ). - ldmulte - Boundary for the load multiplier range of interest (defaults to ). + When ``RangeKey`` = RANGE, the ``LDMULTE`` value is the upper bound for the load multiplier + range of interest ( ``SHIFT`` is the lower bound). - rangekey - Key used to control the behavior of the eigenvalue extraction - method (defaults to CENTER): + rangekey : str + Key used to control the behavior of the eigenvalue extraction method (defaults to CENTER): - CENTER - Use the CENTER option control (default); the program computes NMODE buckling - modes centered around SHIFT in the range of (-LDMULTE, - +LDMULTE). + * ``CENTER`` - Use the CENTER option control (default); the program computes ``NMODE`` buckling + modes centered around ``SHIFT`` in the range of (- ``LDMULTE``, + ``LDMULTE`` ). - RANGE - Use the RANGE option control; the program computes NMODE buckling modes in the - range of (SHIFT, LDMULTE). + * ``RANGE`` - Use the RANGE option control; the program computes ``NMODE`` buckling modes in the + range of ( ``SHIFT``, ``LDMULTE`` ). Notes ----- - Eigenvalues from a buckling analysis can be negative and/or positive. - The program sorts the eigenvalues from the most negative to the most - positive values. The minimum buckling load factor may correspond to the - smallest eigenvalue in absolute value, or to an eigenvalue within the - range, depending on your application (i.e., linear perturbation - buckling analysis or purely linear buckling analysis). - - It is recommended that you request an additional few buckling modes - beyond what is needed in order to enhance the accuracy of the final - solution. It is also recommended that you input a non zero SHIFT value - and a reasonable LDMULTE value (i.e., a smaller LDMULTE that is closer - to the last buckling mode of interest) when numerical problems are - encountered. - - When using the RANGE option, defining a range that spans zero is not - recommended. If you are seeking both negative and positive eigenvalues, - it is recommended that you use the CENTER option. - - This command is also valid in PREP7. If used in SOLUTION, this command - is valid only within the first load step. - - Distributed ANSYS Restriction: Both extraction methods (LANB and SUBSP) - are supported within Distributed ANSYS. However, the subspace iteration - eigensolver (SUBSP) is the only distributed eigensolver that will run a - fully distributed solution. The Block Lanczos eigensolver (LANB) 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. + + .. _BUCOPT_notes: + + Specifies buckling analysis ( :ref:`antype`,BUCKLE) options. Additional options used only for the + Block Lanczos (LANB) eigensolver are specified by the :ref:`lanboption` command. For more difficult + buckling problems, you can specify an alternative version of the Block Lanczos eigensolver ( + :ref:`lanboption`,,,ALT1). + + Eigenvalues from a buckling analysis can be negative and/or positive. The program sorts the + eigenvalues from the most negative to the most positive values. The minimum buckling load factor may + correspond to the smallest eigenvalue in absolute value, or to an eigenvalue within the range, + depending on your application (that is, linear perturbation buckling analysis or purely linear + buckling analysis). + + It is recommended that you request an additional few buckling modes beyond what is needed in order + to enhance the accuracy of the final solution. It is also recommended that you input a non zero + ``SHIFT`` value and a reasonable ``LDMULTE`` value (that is, a smaller ``LDMULTE`` that is closer to + the last buckling mode of interest) when numerical problems are encountered. + + When using the RANGE option, defining a range that spans zero is not recommended. If you are seeking + both negative and positive eigenvalues, it is recommended that you use the CENTER option. + + This command is also valid in PREP7. If used in SOLUTION, this command is valid only within the + first load step. """ command = f"BUCOPT,{method},{nmode},{shift},{ldmulte},{rangekey}" return self.run(command, **kwargs) - def cnvtol(self, lab="", value="", toler="", norm="", minref="", **kwargs): - """Sets convergence values for nonlinear analyses. + def cnvtol( + self, + lab: str = "", + value: str = "", + toler: str = "", + norm: int | str = "", + minref: str = "", + **kwargs, + ): + r"""Sets convergence values for nonlinear analyses. + + Mechanical APDL Command: `CNVTOL `_ + + **Command default:** - APDL Command: CNVTOL + .. _CNVTOL_default: + + For static or transient analysis, check the out-of-balance load for any active degree of freedom + using the default ``VALUE``, ``TOLER``, ``NORM``, and ``MINREF``. Also check the translational + displacement convergence in most cases. For harmonic magnetic analysis, check the out-of-balance of + the degrees of freedom. The energy criterion convergence check is off by default. Parameters ---------- - lab - Valid convergence labels. If STAT, list the status of the currently - specified criteria. + lab : str + Valid convergence labels. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + value : str + Typical reference value for the specified convergence label ( ``Lab`` ). + + ``VALUE`` defaults to the maximum of a program calculated reference or ``MINREF``. For degrees + of freedom, the reference is based upon the selected ``NORM`` and the current total degree-of- + freedom value. For forcing quantities, the reference is based upon the selected ``NORM`` and the + applied loads. + + If ``VALUE`` is negative, the convergence criterion based on the specified label is removed, + including the default convergence criterion value. The convergence criterion for all other + labels remain as they were (either a default value or a previously specified value). + + toler : str + Tolerance value used for the specified ``Lab`` convergence label. Default values are described below. + + * If :ref:`cnvtol` is issued with a ``Lab`` value specified but no ``TOLER`` value, the default + tolerance values are: + + * 0.05 (5%) for displacement (U). + + * 1.0E-7 for the joint element constraint check (JOINT). This value rarely needs to be changed. A + loose tolerance value may lead to inaccurate or incorrect solutions. When ``Lab`` = JOINT, + ``VALUE``, ``NORM``, and ``MINREF`` are ignored. + + * 1.0E-3 for the volumetric compatibility check (COMP). When ``Lab`` = COMP, ``VALUE``, ``NORM``, + and ``MINREF`` are ignored. + + * 0.05 for energy error (ENGY). + + * For all other ``Lab`` labels, the default tolerance value is 0.005 (0.5%). + + * If :ref:`cnvtol` is not issued, the ``TOLER`` defaults are as follows: + + * 0.005 (0.5%) for force (F) and moment (M) + + * 1.0E-4 (0.01%) for volume (DVOL) + + * 0.05 (5%) for displacement (U) - value - Typical reference value for the specified convergence label (Lab). + * 0.05 (5%) for hydrostatic pressure (HDSP) - toler - Tolerance; defaults to 0.005 (0.5%) for force and moment, 1.0E-4 - (0.01%) for DVOL, 0.05 (5%) for displacement when rotational DOFs - are not present, and 0.05 (5%) for HDSP. + * 1.0 for temperature (TEMP) when the iterative QUASI solver is used ( :ref:`thopt`,QUASI,,,,,,1) - norm + If you choose to specify a ``TOLER`` value, it must be greater than zero and less than 1. This is + true for all ``Lab`` labels. + + The program may adjust the force convergence tolerance if you do not explicitly set a value via + :ref:`cnvtol`. See :ref:`Notes for details. ` + + norm : int or str Specifies norm selection: - 2 - L2 norm (check SRSS value). Default, except for Lab = U. + * ``0`` - Infinite norm (check each degree of freedom separately) (default for ``Lab`` = U and for + ``Lab`` = TEMP when the iterative QUASI solver is used ( :ref:`thopt`,QUASI,,,,,,,1). - 1 - L1 norm (check absolute value sum). + The infinite norm is also used for the energy error criterion (ENGY) and is the only option + available for ENGY. - 0 - Infinite norm (check each DOF separately). Default for Lab = U. + * ``1`` - L1 norm (check absolute value sum). - minref - The minimum value allowed for the program calculated reference - value. If negative, no minimum is enforced. Used only if VALUE is - blank. Defaults to 0.01 for force, moment, and volume convergence, - 1.0E-6 for heat flow, 1.0E-12 for VLTG and CHRG, 1.0E-6 for HDSP, - and 0.0 otherwise. + * ``2`` - L2 norm (check SRSS value) (default, except for ``Lab`` = U). - Notes - ----- - This command is usually not needed because the default convergence - criteria are sufficient for most nonlinear analyses. In rare cases, you - may need to use this command to diagnose convergence difficulties. - - Values may be set for the degrees of freedom (DOF) and/or the out-of- - balance load for the corresponding forcing quantities. - - Issuing CNVTOL to set a convergence criterion for a specific - convergence label (Lab) does not affect the convergence criterion for - any other label. All other convergence criteria will remain at their - default setting or at the value set by a previous CNVTOL command. - - When the GUI is on, if a "Delete" operation in a Nonlinear Convergence - Criteria dialog box writes this command to a log file (Jobname.LOG or - Jobname.LGW), you will observe that Lab is blank, VALUE = -1, and TOLER - is an integer number. In this case, the GUI has assigned a value of - TOLER that corresponds to the location of a chosen convergence label in - the dialog box's list. It is not intended that you type in such a - location value for TOLER in an ANSYS session. However, a file that - contains a GUI-generated CNVTOL command of this form can be used for - batch input or with the /INPUT command. - - Convergence norms specified with CNVTOL may be graphically tracked - while the solution is in process using the ANSYS program's Graphical - Solution Tracking (GST) feature. Use the /GST command to turn GST on - or off. By default, GST is ON for interactive sessions and OFF for - batch runs. + * ``3`` - Infinite norm (check each degree of freedom separately). The reference is calculated using + the infinite norm of the displacement increment of the substep. Valid only for ``Lab`` = U. - This command is also valid in PREP7. - """ - command = f"CNVTOL,{lab},{value},{toler},{norm},{minref}" - return self.run(command, **kwargs) + minref : str + The minimum value allowed for the program-calculated reference value. If negative, no minimum is + enforced. Used only if ``VALUE`` is blank. Default values are as follows: - def crplim(self, crcr="", option="", **kwargs): - """Specifies the creep criterion for automatic time stepping. + * maximum of 0.01 or internally calculated minimum reference value for force (F), moment (M) - APDL Command: CRPLIM + * a small factor times the average element length of the model for displacement (U) convergence - Parameters - ---------- - crcr - Value of creep criteria for the creep limit ratio control. + * 0.01 for volume (DVOL) convergence + + * 1.0E-4 for gradient field residual (GFRS) - option - Type of creep analysis for which the creep limit ratio is - specified: + * 1.0E-6 for heat flow (HEAT) - 1 (or ON) - Implicit creep analysis. + * 1.0E-6 for diffusion flow (RATE) - 0 (or OFF) - Explicit creep analysis. + * 1.0E-12 for charge (CHRG) + + * 1.0E-6 for hydrostatic pressure (HDSP) + + * 1.0 for temperature (TEMP) when the iterative QUASI solver is used ( :ref:`thopt`,QUASI,,,,,,,1) + + * 1.0 for energy error convergence (ENGY) + + * 0.0 otherwise Notes ----- - The 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 (i.e., 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. + .. _CNVTOL_notes: + + This command is usually not needed because the default convergence criteria are sufficient for most + nonlinear analyses. In rare cases, you may need to use this command to diagnose convergence + difficulties. + + Values may be set for the degrees of freedom and/or the out-of-balance load for the corresponding + forcing quantities. + + Issuing :ref:`cnvtol` to set a convergence criterion for a specific convergence label ( ``Lab`` ) + does not affect the convergence criterion for any other label. All other convergence criteria will + remain at their default setting or at the value set by a previous :ref:`cnvtol` command. + + If :ref:`cnvtol` is not issued for any force convergence label (F, M, DVOL, and so on as listed + under the ``Lab`` argument), the default convergence tolerance for a particular force label is + increased dynamically during the Newton-Raphson iterations in the range of 1 to 1.66 times the + default value. For example, the F label default tolerance is 0.005. Therefore, the maximum + convergence tolerance with the adjustment is 0.0083. This adjustment is not activated until the 8th + or higher Newton-Raphson iteration. If you do not want the program to adjust the tolerance, issue + :ref:`cnvtol` to specify the convergence tolerance for the appropriate force label. + + When using the Mechanical APDL graphical user interface (GUI), if a "Delete" operation in a + Nonlinear + Convergence Criteria dialog box writes this command to a log file ( :file:`Jobname.LOG` or + :file:`Jobname.LGW` ), you will observe that ``Lab`` is blank, ``VALUE`` = -1, and ``TOLER`` is an + integer number. In this case, the GUI has assigned a value of ``TOLER`` that corresponds to the + location of a chosen convergence label in the dialog box's list. It is not intended that you type in + such a location value for ``TOLER`` in an interactive session. However, a file that contains a GUI- + generated :ref:`cnvtol` command of this form can be used for batch input or with the :ref:`input` + command. + + Convergence norms specified with :ref:`cnvtol` may be graphically tracked while the solution is in + process using the Graphical Solution Tracking (GST) feature. Issue :ref:`gst` to enable or disable + GST. By default, GST is ON for interactive sessions and OFF for batch runs. + + The energy convergence check (ENGY) is not available when the arc-length method ( :ref:`arclen`,ON) + is used. + + For more information on convergence calculations in a nonlinear analysis, see `Convergence + `_ This command is also valid in PREP7. """ - command = f"CRPLIM,{crcr},{option}" + command = f"CNVTOL,{lab},{value},{toler},{norm},{minref}" return self.run(command, **kwargs) - def gst(self, lab="", lab2="", **kwargs): - """Turns Graphical Solution Tracking (GST) on or off. + def gst(self, lab: str = "", runtrack: str = "", **kwargs): + r"""Enables the Graphical Solution Tracking (GST) feature. - APDL Command: /GST + Mechanical APDL Command: `/GST `_ Parameters ---------- - lab - Determines whether the Graphical Solution Tracking feature is - active. Specify ON to activate GST, or OFF to deactivate the - feature. + lab : str + Enables or disables the GST feature: + + * ON - Enable + * OFF - Disable - lab2 - Activates generation of interface and field convergence files - (ANSYS MFX analyses only). + runtrack : str + Enables or disables :file:`.GST` file viewing in the Results Tracker utility: + + * ON - Enable + * OFF - Disable (default) Notes ----- - For interactive runs using GUI [/MENU,ON] or graphics [/MENU,GRPH] - mode, ANSYS directs GST graphics to the screen. For interactive - sessions not using GUI or graphics mode, or for batch sessions, GST - graphics are saved in the ANSYS graphics file Jobname.GST when Lab2 is - unspecified. The file Jobname.GST can be viewed with the DISPLAY - program in this case. You must select All File Types to access it. For - more information on the DISPLAY program see Getting Started with the - DISPLAY Program in the Basic Analysis Guide. For MFX runs (when - Lab2=ON), the Jobname.GST file is in XML format, and it can be viewed - with the Results Tracker Utility, accessed from within the Tools menu - of the Mechanical APDL Product Launcher. - - The GST feature is available only for nonlinear structural, thermal, - electric, magnetic, fluid, or CFD simulations. For more information - about this feature and illustrations of the GST graphics for each - analysis type, see the ANSYS Analysis Guide for the appropriate - discipline. See also the CNVTOL command description. - - When running an ANSYS MFX analysis, specify /GST,ON,ON to generate both - the interface (Jobname.NLH) and field convergence (Fieldname.GST) files - for monitoring the analysis. This field is not available on the GUI. + + .. _s-GST_notes: + + For interactive sessions using the GUI ( :ref:`menu`,ON), GST directs solution graphics to the + screen. + + For interactive sessions not using the GUI ( :ref:`menu`,OFF), or for batch sessions, GST saves + solution graphics to the :file:`Jobname.GST` file. To create a :file:`Jobname.GST` file that is + compatible with the Results Tracker utility (available via the Mechanical APDL Product Launcher ), + issue :ref:`gst`,ON,ON. + + You can use the GST feature for these nonlinear analysis types: structural, thermal, electric, + magnetic, fluid, and diffusion. + + For more information about GST and illustrations of the GST graphics for each analysis type, see the + analysis guide for the appropriate discipline. """ - command = f"/GST,{lab},{lab2}" + command = f"/GST,{lab},{runtrack}" return self.run(command, **kwargs) - def lnsrch(self, key="", **kwargs): - """Activates a line search to be used with Newton-Raphson. + def lnsrch(self, key: str = "", lstol: str = "", lstrun: str = "", **kwargs): + r"""Activates a line search to be used with Newton-Raphson. - APDL Command: LNSRCH + Mechanical APDL Command: `LNSRCH `_ Parameters ---------- - key + key : str Line search key: - OFF - Do not use a line search. + * ``OFF`` - Do not use a line search. - ON - Use a line search. Note, adaptive descent is suppressed when LNSRCH is on - unless explicitly requested on the NROPT command. Having - line search on and adaptive descent on at the same time is not - recommended. + * ``ON`` - Use a line search. Note, adaptive descent is suppressed when :ref:`lnsrch` is on unless + explicitly requested on the :ref:`nropt` command. Having line search on and adaptive descent on at + the same time is not recommended. - AUTO - The program automatically switches line searching ON and OFF between substeps - of a load step as needed. This option is recommended. + * ``AUTO`` - The program automatically switches line searching ON and OFF between substeps of a load + step as needed. This option is recommended. + + lstol : str + Line search convergence tolerance (default = 0.5). + + lstrun : str + Truncation key for the line search parameter. Default = OFF, meaning no truncation. To + activation truncation, input the number of digits to use after the decimal point for the line + search parameter. (See `Line Search + `_ Notes ----- - Activates a line search to be used with the Newton-Raphson method - [NROPT]. Line search is an alternative to adaptive descent (see Line - Search in the Mechanical APDL Theory Reference). - LNSRCH,AUTO can be very efficient for problems in which LNSRCH is - needed at only certain substeps. + .. _LNSRCH_notes: + + Activates a line search to be used with the Newton-Raphson method ( :ref:`nropt` ). Line search is + an alternative to adaptive descent (see `Line Search + `_ - You cannot use line search [LNSRCH], automatic time stepping [AUTOTS], - or the DOF solution predictor [PRED] with the arc-length method - [ARCLEN, ARCTRM]. If you activate the arc-length method after you set - LNSRCH, AUTOTS, or PRED, a warning message appears. If you choose to - proceed with the arc-length method, the program disables your line - search, automatic time stepping, and DOF predictor settings, and the - time step size is controlled by the arc-length method internally. + :ref:`lnsrch`,AUTO can be very efficient for problems in which :ref:`lnsrch` is needed at only + certain substeps. + + You cannot use line search ( :ref:`lnsrch` ), automatic time stepping ( :ref:`autots` ), or the DOF + solution predictor ( :ref:`pred` ) with the arc-length method ( :ref:`arclen`, :ref:`arctrm` ). If + you activate the arc-length method after you set :ref:`lnsrch`, :ref:`autots`, or :ref:`pred`, a + warning message appears. If you choose to proceed with the arc-length method, the program disables + your line search, automatic time stepping, and DOF predictor settings, and the time step size is + controlled by the arc-length method internally. This command is also valid in PREP7. """ - command = f"LNSRCH,{key}" + command = f"LNSRCH,{key},{lstol},{lstrun}" return self.run(command, **kwargs) - def ncnv(self, kstop="", dlim="", itlim="", etlim="", cplim="", **kwargs): - """Sets the key to terminate an analysis. + def ncnv( + self, + kstop: int | str = "", + dlim: str = "", + itlim: str = "", + etlim: str = "", + cplim: str = "", + **kwargs, + ): + r"""Sets the key to terminate an analysis. - APDL Command: NCNV + Mechanical APDL Command: `NCNV `_ Parameters ---------- - kstop + kstop : int or str Program behavior upon nonconvergence: - 0 - Do not terminate the analysis if the solution fails to converge. + * ``0`` - Do not terminate the analysis if the solution fails to converge. - 1 - Terminate the analysis and the program execution if the solution fails to - converge (default). + * ``1`` - Terminate the analysis and the program execution if the solution fails to converge + (default). - 2 - Terminate the analysis, but not the program execution, if the solution fails to - converge. + * ``2`` - Terminate the analysis, but not the program execution, if the solution fails to converge. - dlim - Terminates program execution if the largest nodal DOF solution - value (displacement, temperature, etc.) exceeds this limit. - Defaults to 1.0E6 for all DOF except MAG and A. Defaults to 1.0E10 - for MAG and A. + dlim : str + Terminates program execution if the largest nodal DOF solution value (displacement, temperature, + etc.) exceeds this limit. Defaults to 1.0E6 for all DOF except MAG and A. Defaults to 1.0E10 for + MAG and A. - itlim - Terminates program execution if the cumulative iteration number - exceeds this limit (defaults to infinity). + itlim : str + Terminates program execution if the cumulative iteration number exceeds this limit (defaults to + infinity). - etlim - Terminates program execution if the elapsed time (seconds) exceeds - this limit (defaults to infinity). + etlim : str + Terminates program execution if the elapsed time (seconds) exceeds this limit (defaults to + infinity). - cplim - Terminates program execution if the CPU time (seconds) exceeds this - limit (defaults to infinity). + cplim : str + Terminates program execution if the CPU time (seconds) exceeds this limit (defaults to + infinity). Notes ----- - Sets the key to terminate an analysis if not converged, or if any of - the following limits are exceeded for nonlinear and full transient - analyses: DOF (displacement), cumulative iteration, elapsed time, or - CPU time limit. Applies only to static and transient analyses - (ANTYPE,STATIC and ANTYPE,TRANS). Time limit checks are made at the end - of each equilibrium iteration. + + .. _NCNV_notes: + + Sets the key to terminate an analysis if not converged, or if any of the following limits are + exceeded for nonlinear and full transient analyses: DOF (displacement), cumulative iteration, + elapsed time, or CPU time limit. Applies only to static and transient analyses ( :ref:`antype` + ,STATIC and :ref:`antype`,TRANS). Time limit checks are made at the end of each equilibrium + iteration. This command is also valid in PREP7. """ command = f"NCNV,{kstop},{dlim},{itlim},{etlim},{cplim}" return self.run(command, **kwargs) - def neqit(self, neqit="", forcekey="", **kwargs): - """Specifies the maximum number of equilibrium iterations for nonlinear + def neqit(self, neqit: str = "", forcekey: str = "", **kwargs): + r"""Specifies the maximum number of equilibrium iterations for nonlinear analyses. - APDL Command: NEQIT - analyses. + Mechanical APDL Command: `NEQIT `_ Parameters ---------- - neqit + neqit : str Maximum number of equilibrium iterations allowed each substep. - forcekey + forcekey : str One iteration forcing key: - FORCE - Forces one iteration per substep. Leave this field blank otherwise. + * ``FORCE`` - Forces one iteration per substep. Leave this field blank otherwise. + + Using one iteration per substep may result in unconverged solutions for nonlinear analysis, and the + program may not indicate divergence in this case. This option is intended primarily for use by the + Ansys Workbench interface. Keep in mind that forcing one iteration per substep is only recommended under + very specific conditions; for example, nonlinearity in bonded penalty type contact. Under these + conditions the solution typically converges in one iteration. Notes ----- + + .. _NEQIT_notes: + This command is also valid in PREP7. """ command = f"NEQIT,{neqit},{forcekey}" @@ -483,897 +584,1765 @@ def neqit(self, neqit="", forcekey="", **kwargs): def nladaptive( self, - component="", - action="", - criterion="", - option="", - val1="", - val2="", - val3="", - val4="", + component: str = "", + action: str = "", + criterion: str = "", + option: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", **kwargs, ): - """Defines the criteria under which the mesh is refined or - modified during a nonlinear solution. + r"""Defines the criteria under which the mesh is refined or modified during a nonlinear solution. - APDL Command: NLADAPTIVE + Mechanical APDL Command: `NLADAPTIVE `_ Parameters ---------- component : str - Specifies the element component upon which this command should - act. One of the following: + Specifies the element component upon which this command should act: + + * ``ALL`` - All selected components, or all selected elements if no component is selected (default). - - ``"ALL"`` : All selected components, or all selected - elements if no component is selected (default). - - ``"Name"`` : Component name. + * ``Name`` - Component name. action : str - The action to perform on the selected component(s). One of - the following: - - - ``"ADD"`` : Add a criterion to the database. - - ``"LIST"`` : List the criteria defined for the specified - component(s). - - ``"DELETE"`` : Delete the criteria defined for the specified - component(s). - - ``"ON"`` : Enable the defined criteria for the specified - component(s) and specify how frequently and when to check - them (via ON,,,VAL1,VAL2,VAL3): - - - ``"VAL1"`` : Checking frequency. If > 0, check criteria - at every VAL1 substeps. If < 0, check criteria at each - of the VAL1 points (approximately equally spaced) - between VAL2 and VAL3. (Default = -1.) - - ``"VAL2"`` : Checking start time, where VAL2 < - VAL3. (Default is the start time of the load step.) - - ``"VAL3"`` : Checking end time, where VAL3 > - VAL2. (Default is the end time of the load step.) - - ``"VAL4"`` : SOLID187 element type ID (defined prior to - issuing this command). Valid only for SOLID185 or - SOLID186 components in a NLAD-ETCHG analysis. - - - ``"OFF"`` : Disable the defined criteria for the specified - component(s). - - criterion - The type of criterion to apply to the selected component(s): - - - ``"CONTACT"`` : Contact-based. (Valid only for Action = ADD, - Action = LIST, or Action = DELETE.) - - - ``"ENERGY"`` : Energy-based. (Valid only for Action = ADD, - Action = LIST, or Action = DELETE.) - - - ``"BOX"`` : A position-based criterion, defined by a - box. (Valid only for Action = ADD, Action = LIST, or Action - = DELETE.) - - - ``"MESH"`` : A mesh-quality-based criterion. (Valid only for - Action = LIST, or Action = DELETE.) - - - ``"ALL"`` : All criteria and options. (Valid only for Action - = LIST or Action = DELETE. Option and all subsequent - arguments are ignored.) + Action to perform on the selected component(s): + + * ``ADD`` - Add a criterion to the database. + + * ``LIST`` - List the criteria defined for the specified component(s). + + * ``OCTREE`` - Enable adaptive mesh coarsening for additive manufacturing process simulation using + the AM octree method. + + * ``DELETE`` - Delete the criteria defined for the specified component(s). + + * ``ON`` - Enable the defined criteria for the specified component(s) and specify how frequently and + when to check them (via ON, ``VAL1``, ``VAL2``, ``VAL3`` ): + + ``VAL1`` -- Checking frequency. If > 0, check criteria at every ``VAL1`` substeps. If < 0, check + criteria at each of the ``VAL1`` points (approximately equally spaced) between ``VAL2`` and + ``VAL3``. (Default = -1.) + + ``VAL2`` -- Checking start time, where ``VAL2`` < ``VAL3``. (Default = Start time of load step.) + + ``VAL3`` -- Checking end time, where ``VAL3`` > ``VAL2``. (Default = End time of load step.) + + ``VAL4`` -- ``SOLID187`` element type ID (defined prior to issuing this command). Valid only for + ``SOLID185`` or ``SOLID186`` components in a `NLAD-ETCHG analysis + `_. + + * ``OFF`` - Disable the defined criteria for the specified component(s). + + criterion : str + Type of criterion to apply to the selected component(s): + + * ``CONTACT`` - Contact-based. Valid only for ``Action`` = ADD, ``Action`` = LIST, or ``Action`` = + DELETE. + + * ``ENERGY`` - Energy-based. Valid only for ``Action`` = ADD, ``Action`` = LIST, or ``Action`` = + DELETE. + + * ``BOX`` - A position-based criterion, defined by a box. Valid only for ``Action`` = ADD, + ``Action`` = LIST, or ``Action`` = DELETE. + + * ``MESH`` - A mesh-quality-based criterion. Valid only for ``Action`` = ADD, ``Action`` = LIST, or + ``Action`` = DELETE. + + * ``ALL`` - All criteria and options. Valid only for ``Action`` = LIST or ``Action`` = DELETE. + ``Option`` and all subsequent arguments are ignored. option : str Criterion option to apply to the selected component(s): - - ``"NUMELEM"`` : For target elements only, define the minimum - number of contact elements to contact with each target - element. If this criterion is not satisfied, the program - refines the contact elements and the associated solid - elements. For this option, VAL1 must be a positive - integer. (Valid only for Action = ADD, Action = LIST, or - Action = DELETE. ) - - - ``"MEAN"`` : Check the strain energy of any element that is - part of the defined component for the condition Ee ≥ c1 * - Etotal / NUME (where c1 = VAL1, Etotal is the total strain - energy of the component, and NUME is the number of elements - of the component). If this criterion is satisfied at an - element, the program refines the element. For this option, - VAL1 must be non-negative and defaults to 1. (Valid only for - Action = ADD, Action = LIST, or Action = DELETE.) - - - ``"XYZRANGE"`` : Define the location box in which all - elements within are to be split or refined. Up to six values - following the Option argument (representing the x1, x2, y1, - y2, z1, and z2 coordinates) are allowed. An unspecified - coordinate is not checked. (Valid only for Action = ADD, - Action = LIST, or Action = DELETE.) - - - ``"SKEWNESS"`` : Mesh-quality control threshold for element - SOLID285. Valid values (VAL1) are 0.0 through 1.0. Default = - 0.9. (Valid only for Action = ADD, Action = LIST, or Action - = DELETE.) - - - ``"WEAR"`` : This option is valid only for contact elements - having surface wear specified (TB,WEAR). Define VAL1 as a - critical ratio of magnitude of wear to the average depth of - the solid element underlying the contact element. Once this - critical ratio is reached for any element, the program - morphs the mesh to improve the quality of the elements. VAL1 - must be a positive integer. (Valid only for Action = ADD, - Action = LIST, or Action = DELETE.) The WEAR criterion - cannot be combined with any other criterion. - - - ``"ALL"`` : All options. (Valid only for Action = LIST or - Action = DELETE. All subsequent arguments are ignored.) + * ``NUMELEM`` - For target elements only, defines the minimum number of contact elements to contact + with each target element. If this criterion is not satisfied, the program refines the contact + elements and the associated solid elements. For this option, ``VAL1`` must be a positive integer. + + Valid only for ``Criterion`` = CONTACT and ``Action`` = ADD, LIST, or DELETE. + + * ``MEAN`` - Checks the strain energy of any element that is part of the defined component for the condition E:sub:`e` ≥ c:sub:`1` * E:sub:`total` / ``NUME`` (where c:sub:`1` = ``VAL1``, E:sub:`total` is the total strain energy of the component, and ``NUME`` is the number of elements of the component). If this criterion is satisfied at an element, the program refines the element. ``VAL1`` must be non-negative. Default = 1. + + Valid only for ``Criterion`` = ENERGY and ``Action`` = ADD, LIST, or DELETE. + + * ``XYZRANGE`` - Defines the location box in which all elements within are to be split or refined. + Up to six values following the ``Option`` argument (representing the x1, x2, y1, y2, z1, and z2 + coordinates) are allowed. An unspecified coordinate is not checked. + + Valid only for ``Criterion`` = BOX and ``Action`` = ADD, LIST, or DELETE. + + * ``LAYER`` - Sets layer options for AM octree adaptive meshing for additive simulations. + + * ``VAL1`` - Number of layers to keep at fine mesh resolution between the current, top layer and the + layers to be remeshed. Default = 2. + * ``VAL2`` - Number of buffer elements to keep at fine mesh resolution between the part edges and + the remeshed elements. Default = 2. + + Valid only for ``Action`` = OCTREE. + + * ``SKEWNESS`` - Mesh-quality-control threshold for elements ``SOLID187``, ``SOLID285``, and ``SOLID227`` : + + * ``VAL1`` - Defines skewness. Valid values: 0.0 through 1.0. Default = 0.9. + * ``VAL2`` - Maximum Jacobian ratio at element integration points ( ``SOLID187`` and ``SOLID227`` + only). Valid values: 0.0 to 1.0. Default = 0.1. + + Valid only for ``Criterion`` = MESH and ``Action`` = ADD, LIST, or DELETE. + + * ``SHAPE`` - Mesh-quality control threshold for elements ``PLANE182`` and ``PLANE222``. Also + applies to ``SOLID185`` and ``SOLID186`` in a `NLAD-ETCHG analysis + `_. + + ``VAL1`` -- Maximum corner angle of an element in degrees. Valid values are 0 through 180. Default = + 160 (2D analysis) or 155 (3D analysis). An element is remeshed when any of its corner angles reach + the specified value. + + Valid only for ``Criterion`` = MESH and ``Action`` = ADD, LIST, or DELETE. + + * ``WEAR`` - For contact elements having surface wear specified ( :ref:`tb`,WEAR) only, defines + ``VAL1`` as a critical ratio of magnitude of wear to the average depth of the solid element + underlying the contact element. Once this critical ratio is reached for any element, the program + morphs the mesh to improve the quality of the elements. ``VAL1`` must be a positive integer. + + Valid only for ``Criterion`` = CONTACT and ``Action`` = ADD, ``Action`` = LIST, or ``Action`` = + DELETE. Cannot be combined with any other option during solution. + + * ``CZM`` - For contact elements with `cohesive zone material + `_ + ( :ref:`tb`,CZM) only, defines ``VAL1`` as a critical value of change in released energy due to + debonding between reference and current substep, and ``VAL2`` as the critical value for the change + in the damage parameter between neighboring elements. Both values can be applied separately or + together. + + When the critical value is reached (for either of the defined options) for one contact element, the + solid elements underlying that contact element and the corresponding deformable target element are + selected as candidates for remeshing. + + ``VAL1`` must be > 0. ``VAL2`` must be > 0 and < 1. No default. + + Valid only for ``Criterion`` = CONTACT and ``Action`` = ADD, LIST, or DELETE. Combing the CZM + criterion with `mesh-quality-based + `_ + criteria may be necessary to improve distorted elements. + + * ``ALL`` - All options. Valid only for ``Action`` = LIST or ``Action`` = DELETE. All subsequent + arguments are ignored. + + 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 ----- - If a specified component (Component) is an assembly, the defined - criterion applies to all element components included in the - assembly. - - All components must be defined and selected before the first solve - (SOLVE), although their nonlinear adaptivity criteria can be - modified from load step to load step, and upon restart. For - nonlinear adaptivity to work properly, ensure that all components - are selected before each solve. - - After using this command to define a new criterion, the new - criterion becomes active and is checked one time during each load - step, roughly in mid-loading (unless this behavior is changed via - Action = ON). - - When a criterion is defined, it overwrites a previously defined - criterion (if one exists) through the same component, or through - the component assembly that includes the specified component. - - During solution, the same criteria defined for an element through - different components are combined, and the tightest criteria and - action control (Action,ON,,,VAL1) are used. If an ON action is - defined by a positive VAL1 value through one component and a - negative VAL1 value through another, the program uses the positive - value. - - For ``action="ON"``, if VAL2 (start time) and/or VAL3 (end time) - are unspecified or invalid, the program uses the start and/or end - time (respectively) of the load step. If VAL1 < 0, the program - checks VAL1 points between VAL2 and VAL3. The time interval - between each check points is determined by (VAL3 - VAL2) / (VAL1 + - 1), with the first check point as close to VAL2 + (VAL3 - VAL2) / - (VAL1 + 1) as possible. Fewer check points can be used if the - number of substeps during solution is insufficient (as the program + + .. _NLADAPTIVE_notes: + + If a specified component ( ``Component`` ) is an assembly, the defined criterion applies to all + element components included in the assembly. + + All components must be defined and selected before the first solve ( :ref:`solve` ), although their + nonlinear adaptivity criteria can be modified from load step to load step, and upon restart. For + nonlinear adaptivity to work properly, ensure that all components are selected before each solve. + + After issuing this command to define a new criterion, the new criterion becomes active. The program + checks the new criterion once per load step, roughly in mid-loading (unless this behavior is changed + via ``Action`` = ON). + + When a criterion is defined, it overwrites a previously defined criterion (if one exists) through + the same component, or through the component assembly that includes the specified component. + + During solution, the same criteria defined for an element through different components are combined, + and the tightest criteria and action control ( ``Action``,ON, ``VAL1`` ) are used. If an ON action + is defined by a positive ``VAL1`` value through one component and a negative ``VAL1`` value through + another, the program uses the positive value. + + When the AM octree option is specified ( ``Action`` = OCTREE), the checking frequency ( Action,ON,, + VAL1 ), checking start time ( Action,ON, VAL2 ), and checking end time ( Action,ON, VAL3 ) + control the checking layer frequency, start layer, and end layer respectively. If start and end + layers are not specified, the start layer will default to the checking frequency, and the end layer + will default to the final layer of the AM simulation. + + If ``VAL1`` < 0, the program checks ``VAL1`` points between ``VAL2`` and ``VAL3``. The time interval + between each check points is determined by ( ``VAL3`` - ``VAL2`` ) / ( ``VAL1`` + 1), with the first + check point as close to ``VAL2`` + ( ``VAL3`` - ``VAL2`` ) / ( ``VAL1`` + 1) as possible. Fewer + check points can be used if the number of substeps during solution is insufficient (as the program can only check at the end of a substep). - Option = SKEWNESS applies to linear tetrahedral element SOLID285 - only. When the skewness of a SOLID285 element is >= the defined - value, the element is used as the core (seed) element of the - remeshed region(s). If this criterion is used together with any - other criteria for the same component, the other criteria defined - for the component are ignored. The most desirable skewness value - is 0, applicable when the element is a standard tetrahedral - element; the highest value is 1, applicable when the element - becomes flat with zero volume. For more information about skewness - and remeshing, see Mesh Nonlinear Adaptivity in the Advanced - Analysis Guide. - - For more granular control of the source mesh geometry, see NLMESH. + If ``VAL2`` (start time) and/or ``VAL3`` (end time) are unspecified or invalid, the program uses the + start and/or end time (respectively) of the load step. + + ``VAL1`` applies to tetrahedral elements ``SOLID187``, ``SOLID227``, and ``SOLID285``. When the + skewness of an element is >= ``VAL1``, the element is used as the core (seed) element of the + remeshed region(s). The most desirable skewness value is 0, applicable when the element is a + standard tetrahedral element; the highest value is 1, applicable when the element becomes flat with + zero volume. To bypass skewness checking (not recommended), set ``VAL1`` = 0. + + ``VAL2`` represents the Jacobian ratio and is required for tetrahedral elements ``SOLID187`` and + ``SOLID227``. When the maximum Jacobian ratio of an element is <= ``VAL2``, the element is used as + the core (seed) element of the remeshed region(s). The most desirable maximum Jacobian ratio is 1, + when the element is a standard tetrahedral element; the lowest reported value is -1, when the + element is turned inside out. To bypass maximum Jacobian ratio checking (not recommended), set + ``VAL2`` = 0. + + If this criterion is used with any other criteria defined for the same component, and a mesh change + is requested at the same substep, all criteria defined are considered together. For more information + about this special case, see `Simultaneous Quality- and Refinement-Based Remeshing + `_ + + For more information about skewness, maximum Jacobian ratio, and remeshing, see `Nonlinear Mesh + Adaptivity `_ + + For more granular control of the source mesh geometry, see :ref:`nlmesh`. """ command = f"NLADAPTIVE,{component},{action},{criterion},{option},{val1},{val2},{val3},{val4}" return self.run(command, **kwargs) - def nldiag(self, label="", key="", maxfile="", **kwargs): - """Sets nonlinear diagnostics functionality. + def nldiag(self, label: str = "", key: str = "", maxfile: str = "", **kwargs): + r"""Sets nonlinear diagnostics functionality. - APDL Command: NLDIAG + Mechanical APDL Command: `NLDIAG `_ Parameters ---------- - label + label : str Diagnostic function: - NRRE - Store the Newton-Raphson residuals information. + * ``NRRE`` - Store the Newton-Raphson residuals information. - EFLG - Identify or display elements or nodes that violate the criteria. + * ``EFLG`` - Identify or display elements or nodes that violate the criteria. - CONT - Write contact information to a single Jobname.cnd diagnostic text file during - solution. + * ``CONT`` - Write contact information to a single :file:`Jobname.cnd` diagnostic text file during + solution. - key + key : str Diagnostic function characteristics: - OFF or 0 - Suppresses writing of diagnostic information (default). + * ``OFF or 0`` - Suppresses writing of diagnostic information (default). - ON or 1 - Writes diagnostic information to the Jobname.ndxxx, Jobname.nrxxx, or - Jobname.cnd file. (If Label = CONT, this option is the - same as the SUBS option described below.) + * ``ON or 1`` - Writes diagnostic information to the :file:`Jobname.ndxxx`, :file:`Jobname.nrxxx`, + or :file:`Jobname.cnd` file. (If ``Label`` = CONT, this option is the same as the SUBS option + described below.) - ITER - Writes contact diagnostic information at each iteration. Valid only when Label - = CONT. + * ``ITER`` - Writes contact diagnostic information at each iteration. Valid only when ``Label`` = + CONT. - SUBS - Writes contact diagnostic information at each substep. Valid only when Label = - CONT. + * ``SUBS`` - Writes contact diagnostic information at each substep. Valid only when ``Label`` = + CONT. - LSTP - Writes contact diagnostic information at each load step. Valid only when Label - = CONT. + * ``LSTP`` - Writes contact diagnostic information at each load step. Valid only when ``Label`` = + CONT. - STAT - Lists information about the diagnostic files in the current working directory. + * ``STAT`` - Lists information about the diagnostic files in the current working directory. - DEL - Deletes all diagnostic files in the current working directory. + * ``DEL`` - Deletes all diagnostic files in the current working directory. - maxfile - Maximum number of diagnostic files to create. Valid values are 1 - through 999. Default = 4. Valid only when Label = NRRE or EFLG. + maxfile : str + Maximum number of diagnostic files to create. Valid values are 1 through 999. Default = 4. Valid + only when ``Label`` = NRRE or EFLG. + + Information is written to :file:`Jobname.ndxxx` or :file:`Jobname.nrxxx`, where ``xxx`` iterates + from 001 through ``MAXFILE``. When the specified maximum number of diagnostic files is reached, + the counter resets to 001 and earlier files are overwritten. The ``MAXFILE`` value specified for + this ``Label`` function applies until a new value is specified. Notes ----- - The NLDIAG command is a nonlinear diagnostics tool valid for nonlinear - structural analyses. It is a debugging tool for use when you must - restart after an unconverged solution. The command creates - Jobname.ndxxx, Jobname.nrxxx, or Jobname.cnd files in the working - directory to store the information you specify. - For more information, see Performing Nonlinear Diagnostics. + .. _NLDIAG_notes: + + The :ref:`nldiag` command is a nonlinear diagnostics tool valid for nonlinear analyses that include + structural degrees of freedom. It is a debugging tool for use when you must restart after an + unconverged solution. The command creates :file:`Jobname.ndxxx`, :file:`Jobname.nrxxx`, or + :file:`Jobname.cnd` files in the working directory to store the information you specify. + + For more information, see. + + Issue the :ref:`nldiag`,NRRE,ON command to create :file:`Jobname.nrxxx` diagnostic files (for each + equilibrium iteration after the first) in which to store the relevant Newton-Raphson residual + information of FX, FY, FZ (forces), MX, MY, MZ (moments), HEAT (heat flow), AMPS (current flow), + CHRG (electric charge), or RATE (diffusion flow rate) for the last ``MAXFILE`` equilibrium + iterations. + + Issue a :ref:`nldpost`,NRRE,STAT command to list the load step, substep, time, and equilibrium + iteration corresponding to each of the :file:`Jobname.nrxxx` diagnostic files in the working + directory, then issue a :ref:`plnsol`,NRRES,, ``FileID`` command to point to the file from which + you want to create a contour plot of your Newton-Raphson residuals. + + If you restart or issue a new :ref:`solve` command, any :file:`Jobname.nrxxx` diagnostic files in + the current (working) directory are overwritten. + + Issue a :ref:`nldiag`,EFLG,ON command to create :file:`Jobname.ndxxx` diagnostic files which store + IDs for elements violating the following criteria: + + * Too large a distortion (HDST) + + * Elements contain nodes that have near zero pivots (PIVT) for nonlinear analyses + + * Too large a plastic/creep (EPPL/EPCR) strain increment ( :ref:`cutcontrol` ) + + * Elements for which mixed u-P constraints are not satisfied (mixed U-P option of 18 ``x`` solid + elements only) (MXUP) + + * Hyperelastic element (EPHY), cohesive zone material (EPCZ), or damage strain (EPDM) not converged + + * Radial displacement (RDSP) not converged + + * ``MPC184`` multipoint constraint elements using KEYOPT(1) = 6 through 16 with the Lagrange + multiplier option fail to satisfy constraint conditions (184J) + + For :ref:`nldiag`,EFLG,ON, all :file:`Jobname.ndxxx` diagnostic files (for each equilibrium + iteration after the first) in the current (working) directory are deleted when you issue a new + :ref:`solve` command (or restart). + + In the solution processor ( :ref:`slashsolu` ), use the STAT option to list the active status of + this command. In the postprocessor ( :ref:`post1` ), issue a :ref:`nldpost`,EFLG,STAT command to + list the load step, substep, time, and equilibrium iteration corresponding to each of the + :file:`Jobname.ndxxx` diagnostic files in the working directory, then issue a + :ref:`nldpost`,EFLG,CM, ``FileID`` command to create element components that violate the criteria. - Issue the NLDIAG,NRRE,ON command to create Jobname.nrxxx diagnostic - files (for each equilibrium iteration after the first) in which to - store the relevant Newton-Raphson residual information of - forces/moments Fx, Fy, Fz, Mx, My and Mz for the last MAXFILE - equilibrium iterations. + Issue the :ref:`nldiag`,CONT,ON command to create a :file:`Jobname.cnd` diagnostic file which stores + contact information for all defined contact pairs at all substeps. Alternatively, you may issue one + of the following commands to store contact information at a specific frequency: - Issue a NLDPOST,NRRE,STAT command to list the load step, substep, time, - and equilibrium iteration corresponding to each of the Jobname.nrxxx - diagnostic files in the working directory, then issue a - PLNSOL,NRRES,,,,FileID command to point to the file from which you want - to create a contour plot of your Newton-Raphson residuals. + * :ref:`nldiag`,CONT,ITER to write at each iteration - If you restart or issue a new SOLVE command, any Jobname.nrxxx - diagnostic files in the current (working) directory are overwritten. + * :ref:`nldiag`,CONT,SUBS to write at each substep (default) - Issue a NLDIAG,EFLG,ON command to create Jobname.ndxxx diagnostic - files which store IDs for elements violating the following criteria: + * :ref:`nldiag`,CONT,LSTP to write at each load step - Too large a distortion (HDST) + Contact diagnostic information is available for elements ``CONTA172``, ``CONTA174``, ``CONTA175``, + and ``CONTA177`` ; it is not available for ``CONTA178``. - Elements contain nodes that have near zero pivots (PIVT) for nonlinear - analyses + Diagnostic file :file:`Jobname.cnd` is written during solution and lists, on a pair-base, the + following contact information: - Too large a plastic/creep (EPPL/EPCR) strain increment (CUTCONTROL) + * Contact pair ID :ref:`NLDIAGfootnt1` :sup:`[1]` - Elements for which mixed u-P constraints are not satisfied (mixed U-P - option of 18x solid elements only) (MXUP) + * Number of contact elements in contact :ref:`NLDIAGfootnt2` :sup:`[2]` - Hyperelastic element (EPHY), cohesive zone material (EPCZ), or damage - strain (EPDM) not converged + * Number of contact elements in sticking contact status - Radial displacement (RDSP) not converged + * Maximum chattering level - MPC184 multipoint constraint elements using KEYOPT(1) = 6 through 16 - with the Lagrange multiplier option fail to satisfy constraint - conditions (184J) + * Maximum contact penetration/Minimum gap :ref:`NLDIAGfootnt3` :sup:`[3]` - For NLDIAG,EFLG,ON, all Jobname.ndxxx diagnostic files (for each - equilibrium iteration after the first) in the current (working) - directory are deleted when you issue a new SOLVE command (or restart). + * Maximum geometric gap - In the solution processor (/SOLU), use the STAT option to list the - active status of this command. In the postprocessor (/POST1), issue a - NLDPOST,EFLG,STAT command to list the load step, substep, time, and - equilibrium iteration corresponding to each of the Jobname.ndxxx - diagnostic files in the working directory, then issue a - NLDPOST,EFLG,CM,FileID command to create element components that - violate the criteria. + * Maximum normal contact stiffness - Issue the NLDIAG,CONT,ON command to create a Jobname.cnd diagnostic - file which stores contact information for all defined contact pairs at - all substeps. Alternatively, you may issue one of the following - commands to store contact information at a specific frequency: + * Minimum normal contact stiffness - NLDIAG,CONT,ITER to write at each iteration + * Maximum resulting pinball - NLDIAG,CONT,SUBS to write at each substep (default) + * Maximum elastic slip distance - NLDIAG,CONT,LSTP to write at each load step + * Maximum tangential contact stiffness - Contact diagnostic information is available for elements CONTA171 - through CONTA177; it is not available for CONTA178. + * Minimum tangential contact stiffness - Diagnostic file Jobname.cnd is written during solution and lists, on a - pair-base, the following contact information: + * Maximum sliding distance (algebraic sum) - Contact pair ID[1] + * Maximum contact pressure - Number of contact elements in contact[2] + * Maximum friction stress - Number of contact elements in "sticking" contact status + * Average contact depth - Maximum chattering level + * Maximum geometric penetration - Maximum contact penetration/Minimum gap[3] + * Number of contact points having too much penetration - Maximum closed gap + * Contacting area - Maximum normal contact stiffness + * Maximum contact damping pressure - Minimum normal contact stiffness + * Maximum tangential contact damping stress - Maximum resulting pinball + * Maximum total sliding distance ( GSLID ), including near-field - Maximum elastic slip distance + * Minimum total sliding distance ( GSLID ), including near-field - Maximum tangential contact stiffness + * Maximum normal fluid penetration pressure on contact surface - Minimum tangential contact stiffness + * Maximum normal fluid penetration pressure on target surface - Maximum sliding distance + * Total volume lost due to wear for the contact pair - Maximum contact pressure + * Total strain energy due to contact constraint :ref:`NLDIAGfootnt6` :sup:`[6]` - Maximum friction stress + * Total frictional dissipation energy :ref:`NLDIAGfootnt6` :sup:`[6]` - Average contact depth + * Total contact stabilization energy :ref:`NLDIAGfootnt6` :sup:`[6]` - Maximum closed penetration + * Ansys Workbench contact pair ID :ref:`NLDIAGfootnt4` :sup:`[4]` - Number of contact points having too much penetration + * Total force due to contact pressure - X component - Contacting area + * Total force due to contact pressure - Y component - Maximum contact damping pressure + * Total force due to contact pressure - Z component :ref:`NLDIAGfootnt5` :sup:`[5]` - Maximum tangential contact damping stress + * Total force due to tangential stress - X component - Maximum total sliding distance (GSLID), including near-field + * Total force due to tangential stress - Y component - Minimum total sliding distance (GSLID), including near-field + * Total force due to tangential stress - Z component :ref:`NLDIAGfootnt5` :sup:`[5]` - Maximum fluid penetration pressure on contact surface + * Number of contact points having too much sliding for small sliding contact - Maximum fluid penetration pressure on target surface + * Pair-based force convergence norm :ref:`NLDIAGfootnt7` :sup:`[7]` - Total volume lost due to wear for the contact pair + * Pair-based force convergence criterion :ref:`NLDIAGfootnt7` :sup:`[7]` - Total strain energy due to contact constraint + * Maximum tangential fluid penetration pressure on contact surface - Total frictional dissipation energy + * Maximum tangential fluid penetration pressure on target surface - Total contact stabilization energy + * Maximum sliding distance for closed contact in the current substep - ANSYS Workbench contact pair ID[4] + .. _NLDIAGfootnt1: + + Contact pair ID. A positive number refers to a real constant ID for a pair-based contact definition. + A negative number refers to a section ID of a surface in a general contact definition. (See + `Comparison of Pair-Based Contact and General Contact + `_ + + .. _NLDIAGfootnt2: + + Number of contact elements in contact. Other values are interpreted as follows: + + * 0 indicates that the contact pair is in near-field contact status. * -1 indicates that the contact + pair is in far-field contact status. * -2 indicates that the contact pair is inactive ( symmetric to + asymmetric contact ). + + .. _NLDIAGfootnt3: + + A positive value indicates penetration and a negative value indicates a gap. If the contact pair has + a far-field contact status, penetration and gap are not available and the value stored is the + current pinball radius. + + .. _NLDIAGfootnt4: + + Intended primarily for internal use in the contact tracking of Ansys Workbench. + + .. _NLDIAGfootnt5: + + In a 3D model, the reported item is total force along the Z-axis. In a 2D axisymmetric model (with + or without ROTY), the reported item is maximum torque that can potentially act on the Y-axis. + + .. _NLDIAGfootnt6: + + The pair-based dissipation energy and stabilization energy do not include contributions from contact + elements that are in far-field. The pair-based strain energy does not include the frictional + dissipation energy and stabilization energy; it only contains an elastic recovery energy when the + contact status changes from closed to open. + + .. _NLDIAGfootnt7: + + The program uses a default tolerance value of 0.1 to calculate the pair-based force convergence norm + and pair-based force convergence criterion. This is not a check for local convergence. It is for + monitoring purposes only and is useful for nonlinear contact diagnostics. + + In the solution processor ( :ref:`slashsolu` ), use the :ref:`nldiag`,CONT,STAT command to list the + active status of the contact information. If you subsequently issue a new :ref:`solve` command (or + restart), the :file:`Jobname.cnd` diagnostic file in the current (working) directory is not deleted; + information is appended to it. Delete the existing diagnostic file ( :ref:`nldiag`,CONT,DEL command) + if you do not want to retain diagnostic information from previous solutions. """ command = f"NLDIAG,{label},{key},{maxfile}" return self.run(command, **kwargs) - def nlgeom(self, key="", **kwargs): - """Includes large-deflection effects in a static or full transient + def nlgeom(self, key: str = "", **kwargs): + r"""Includes large-deflection effects in a static or full transient analysis. - APDL Command: NLGEOM - analysis. + Mechanical APDL Command: `NLGEOM `_ Parameters ---------- - key + key : str Large-deflection key: - OFF - Ignores large-deflection effects (that is, a small-deflection analysis is - specified). This option is the default. + * ``OFF`` - Ignores large-deflection effects (that is, a small-deflection analysis is specified). + This option is the default. - ON - Includes large-deflection (large rotation) effects or large strain effects, - according to the element type. + * ``ON`` - Includes large-deflection (large rotation) effects or large strain effects, according to + the element type. Notes ----- - Large-deflection effects are categorized as either large deflection (or - large rotation) or large strain, depending on the element type. These - are listed (if available) under Special Features in the input data - table for each element in the Element Reference. When large deflection - effects are included (NLGEOM,ON), stress stiffening effects are also - included automatically. - If used during the solution (/SOLU), this command is valid only within - the first load step. + .. _NLGEOM_notes: - In a large-deflection analysis, pressure loads behave differently than - other load types. For more information, see Load Direction in a Large- - Deflection Analysis. + Large-deflection effects are categorized as either large deflection (or large rotation) or large + strain, depending on the element type. These are listed (if available) under Special Features in the + input data table for each element in the `Element Reference + `_. When large + deflection effects are included ( + :ref:`nlgeom`,ON), stress stiffening effects are also included automatically. - The gyroscopic matrix (that occurs due to rotational angular velocity) - does not support large-deflection effects. The theoretical formulations - for the gyroscopic matrix support small deflection (linear formulation) - only. + If used during the solution ( :ref:`slashsolu` ), this command is valid only within the first load + step. - When large-deflection effects are included in a substructure or CMS - transient analysis use pass, the OUTRES command ignores DSUBres = ALL. + In a large-deflection analysis, pressure loads behave differently than other load types. For more + information, see `Load Direction in a Large-Deflection Analysis + `_. - This command is also valid in PREP7. + The gyroscopic matrix (that occurs due to rotational angular velocity) does not support large- + deflection effects. The theoretical formulations for the gyroscopic matrix support small deflection + (linear formulation) only. - In ANSYS Professional NLT, large deflection effects should not be - turned on if 2-D solid (PLANEn) or 3-D solid (SOLIDn) elements are - defined. ANSYS Professional NLS supports NLGEOM,ON for plane and solid - elements. + When large-deflection effects are included in a substructure or CMS transient analysis use pass, the + :ref:`outres` command ignores ``DSUBres`` = ALL. + + This command is also valid in PREP7. """ command = f"NLGEOM,{key}" return self.run(command, **kwargs) def nlhist( self, - key="", - name="", - item="", - comp="", - node="", - elem="", - shell="", - layer="", - stop_value="", - stop_cond="", + key: str = "", + name: str = "", + item: str = "", + comp: str = "", + node: str = "", + elem: str = "", + shell: str = "", + layer: str = "", + stop_value: str = "", + stop_cond: int | str = "", **kwargs, ): - """Specify result items to track during solution. + r"""Specify results items to track during solution. - APDL Command: NLHIST + Mechanical APDL Command: `NLHIST `_ Parameters ---------- - key + key : str Specifies the command operation: - NSOL - Nodal solution data. + * ``NSOL`` - Nodal solution data. + + * ``ESOL`` - Element nodal data. - ESOL - Element nodal data. + * ``PAIR`` - Contact data (for pair-based contact). - PAIR - Contact data (for pair-based contact). + * ``GCN`` - Contact data (for general contact). - GCN - Contact data (for general contact). + * ``RSEC`` - `Result section + `_ data. - STAT - Displays a list of items to track. + * ``STAT`` - Displays a list of items to track. - OFF or 0 - Deactivates tracking of all variables. This value is the default. + * ``OFF or 0`` - Deactivates tracking of all variables. This value is the default. - ON or 1 - Activates tracking of all variables. Tracking also activates whenever any - specification changes. + * ``ON or 1`` - Activates tracking of all variables. Tracking also activates whenever any + specification changes. - DEL - Removes the specified variable from the set of result items to track. If Name = - ALL (default), all specifications are removed. + * ``DEL`` - Removes the specified variable from the set of result items to track. If ``Name`` = ALL + (default), all specifications are removed. - name + name : str The 32-character user-specified name. - item, comp - Predetermined output item and component label for valid elements. - See the Element Reference for more information. + item : str + Predetermined output item and component label for valid elements. See the `Element Reference + `_ for more + information. - node + comp : str + Predetermined output item and component label for valid elements. See the `Element Reference + `_ for more + information. + + node : str Number identifying one of the following: - elem - Valid element number for element results. Used for ESOL items. If - ELEM is specified, then a node number that belongs to the element - must also be specified in the NODE field. + * Valid node number (if ``Key`` = NSOL or ESOL). + * Valid real constant set number identifying a contact pair (if ``Key`` = PAIR). + * Valid section ID number identifying a surface of a general contact definition (if ``Key`` = GCN). + * Valid real constant set number identifying a result section (if ``Key`` = RSEC). + ``NODE`` is required input when ``Key`` = NSOL, ESOL, PAIR, GCN, or RSEC. + + elem : str + Valid element number for element results. Used for ESOL items. If ``ELEM`` is specified, then a + node number that belongs to the element must also be specified in the ``NODE`` field. - shell - Valid labels are TOP, MID or BOT. This field can specify the - location on shell elements for which to retrieve data. Used only - for element nodal data (ESOL). + shell : str + Valid labels are TOP, MID or BOT. This field can specify the location on shell elements for + which to retrieve data. Used only for element nodal data (ESOL). - layer - Layer number (for layered elements only). Used only for element - nodal data (ESOL). + layer : str + Layer number (for layered elements only). Used only for element nodal data (ESOL). - stop_value - Critical value of the tracked variable. This value is used to - determine if the analysis should be terminated. This field is only - valid for contact data (Key = PAIR or GCN). + stop_value : str + Critical value of the tracked variable. This value is used to determine if the analysis should + be terminated. - stop_cond - Specifies the conditional relationship between the variable being - tracked and the STOP_VALUE upon which the analysis will be - terminated: + stop_cond : int or str + Specifies the conditional relationship between the variable being tracked and the ``STOP_VALUE`` upon which the analysis will be terminated: - -1 - Terminate the analysis when the tracked variable is less than or equal to - STOP_VALUE. + * ``-1`` - Terminate the analysis when the tracked variable is less than or equal to ``STOP_VALUE``. - 0 - Terminate the analysis when the tracked variable equals STOP_VALUE. + * ``0`` - Terminate the analysis when the tracked variable equals ``STOP_VALUE``. - 1 - Terminate the analysis when the tracked variable is greater than or equal to - STOP_VALUE. + * ``1`` - Terminate the analysis when the tracked variable is greater than or equal to + ``STOP_VALUE``. Notes ----- - The NLHIST command is a nonlinear diagnostics tool that enables you to - monitor diagnostics results of interest in real time during a solution. - - You can track a maximum of 50 variables during solution. The specified - result quantities are written to the file Jobname.nlh. Nodal results - and contact results are written for every converged substep - (irrespective of the OUTRES command setting) while element results are - written only at time points specified via the OUTRES command. For time - points where element results data is not available, a very small number - is written instead. If the conditions for contact to be established are - not satisfied, 0.0 will be written for contact results. - - Results tracking is available only for a nonlinear structural analysis - (static or transient), a nonlinear steady-state thermal analysis, or a - transient thermal analysis (linear or nonlinear). All results are - tracked in the Solution Coordinate System (that is, nodal results are - in the nodal coordinate system and element results are in the element - coordinate system). - - Contact results can be tracked for elements CONTA171 through CONTA177; - they cannot be tracked for CONTA178. - - When contact results are tracked (Key = PAIR or GCN), the user- - specified name (Name argument) is used to create a user-defined - parameter. This enables you to monitor the parameter during solution. - As an example, you can use a named parameter to easily convert the - contact stiffness units from FORCE/LENGTH3 to FORCE/LENGTH based on the - initial contact area CAREA. Be sure to specify Name using the APDL - parameter naming convention. - - The STOP_VALUE and STOP_COND arguments enable you to automatically - terminate the analysis when a desired value for a tracked contact - result has been reached. This capability is only available for contact - variables (Key = PAIR or GCN). - - The Jobname.nlh file is an ASCII file that lists each time point at - which a converged solution occurs along with the values of the relevant - result quantities. - - The GUI option Solution> Results tracking provides an interface to - define the result items to be tracked. The GUI also allows you to graph - one or more variables against time or against other variables during - solution. You can use the interface to graph or list variables from any - .nlh file generated by the ANSYS program. - - You can also track results during batch runs. Either access the ANSYS - Launcher and select File Tracking from the Tools menu, or type - nlhist162 at the command line. Use the supplied file browser to - navigate to your Jobname.nlh file, and click on it to invoke the - tracking utility. You can use this utility to read the file at any - time, even after the solution is complete (the data in the file must be - formatted correctly). - - Table: 205:: : NLHIST - Valid NSOL Item and Component Labels - - For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use the - labels TBOT, TE2, TE3, . . ., TTOP instead of TEMP. - - For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use the - labels HBOT, HE2, HE3, . . ., HTOP instead of HEAT. - - Table: 206:: : NLHIST - Valid ESOL Item and Component Labels + + .. _NLHIST_notes: + + The :ref:`nlhist` command is a nonlinear diagnostics tool that enables you to monitor diagnostics + results of interest in real time during a solution. + + You can track a maximum of 50 variables during solution. The specified result quantities are written + to the file :file:`Jobname.nlh`. Nodal results and contact results are written for every converged + substep (irrespective of the :ref:`outres` command setting), while element results are written only + at time points specified via the :ref:`outres` command. Result section data is written only at time + points specified via the :ref:`outpr`,RSO, ``Freq`` command. + + For time points where element results data is not available, a very small number is written instead. + If the conditions for contact to be established are not satisfied, 0.0 will be written for contact + results. + + Results tracking is available for: + + * nonlinear structural analyses (static or transient) + + * nonlinear steady-state thermal analyses + + * transient thermal analyses (linear or nonlinear) + + * nonlinear coupled structural-thermal analyses (static or transient) + + All results are tracked in the Solution Coordinate System (that is, nodal results are in the nodal + coordinate system and element results are in the element coordinate system). + + Contact results can be tracked for elements ``CONTA172``, ``CONTA174``, ``CONTA175``, and + ``CONTA177`` ; they cannot be tracked for ``CONTA178``. + + `Result section + `_ data can be + tracked for elements ``CONTA172`` and ``CONTA174``. + + When contact results ( ``Key`` = PAIR or GCN) or result section data ( ``Key`` = RSEC) are tracked, + the user-specified name ( ``Name`` argument) is used to create a user-defined parameter. This + enables you to monitor the parameter during solution. As an example, you can use a named parameter + to easily convert the contact stiffness units from FORCE/LENGTH :sup:`3` to FORCE/LENGTH based on + the initial contact area CAREA. Be sure to specify ``Name`` using the `APDL parameter naming + convention + `_. + + The ``STOP_VALUE`` and ``STOP_COND`` arguments enable you to automatically terminate the analysis + when a desired value for a tracked contact result or section result has been reached. This + capability is only available for contact variables ( ``Key`` = PAIR or GCN) and result section + variables ( ``Key`` = RSEC ). + + The :file:`Jobname.nlh` file is an ASCII file that lists each time point at which a converged + solution occurs along with the values of the relevant result quantities. + + The GUI option Solution> Results tracking provides an interface to define the result items to be + tracked. The GUI also allows you to graph one or more variables against time or against other + variables during solution. You can use the interface to graph or list variables from any + :file:`.nlh` file generated by Mechanical APDL. + + You can also track results during batch runs. Either access the `launcher + `_ + and select ``Run Results Tracker Utility`` from the Tools menu, or type + :file:`nlhist232` at the command line. Use the supplied file browser to + navigate to your :file:`Jobname.nlh` file, and click on it to invoke the tracking utility. You can + use this utility to read the file at any time, even after the solution is complete (the data in the + file must be formatted correctly). + + .. _nlhist_nsol_tab: + + NLHIST - Valid NSOL Item and Component Labels + ********************************************* + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - U + - X, Y, Z + - X, Y, or Z structural displacement. + * - ROT + - X, Y, Z + - X, Y, or Z structural rotation. + * - F + - X, Y, Z + - X, Y, or Z structural reaction force. + * - M + - X, Y, Z + - X, Y, or Z structural reaction moment. + * - TEMP [ :ref:`nlhist_nsol_tabnote1` ] + - - + - Temperature. + * - TEMP + - MAX, MIN + - Maximum or minimum temperature in the model. + * - HEAT [ :ref:`nlhist_nsol_tabnote2` ] + - - + - Reaction heat flow. + + .. _nlhist_nsol_tabnote1: + + For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels TBOT, TE2, TE3,. + .., TTOP instead of TEMP. + + .. _nlhist_nsol_tabnote2: + + For ``SHELL131`` and ``SHELL132`` elements with KEYOPT(3) = 0 or 1, use the labels HBOT, HE2, HE3,. + .., HTOP instead of HEAT. + + .. _nlhist_tab_1: + + NLHIST - Valid ESOL Item and Component Labels + ********************************************* + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - S + - X, Y, Z, XY, YZ, XZ + - Component stress. + * - " + - 1, 2, 3 + - Principal stress. + * - " + - INT + - Stress intensity. + * - " + - EQV + - Equivalent stress. + * - EPEL + - X, Y, Z, XY, YZ, XZ + - Component elastic strain. + * - " + - 1, 2, 3 + - Principal elastic strain. + * - " + - INT + - Elastic strain intensity. + * - " + - EQV + - Elastic equivalent strain. + * - EPPL + - X, Y, Z, XY, YZ, XZ + - Component plastic strain. + * - " + - 1, 2, 3 + - Principal plastic strain. + * - " + - INT + - Plastic strain intensity. + * - " + - EQV + - Plastic equivalent strain. + * - EPCR + - X, Y, Z, XY, YZ, XZ + - Component creep strain. + * - " + - 1, 2, 3 + - Principal creep strain. + * - " + - INT + - Creep strain intensity. + * - " + - EQV + - Creep equivalent strain. + * - EPTH + - X, Y, Z, XY, YZ, XZ + - Component thermal strain. + * - " + - 1, 2, 3 + - Principal thermal strain. + * - " + - INT + - Thermal strain intensity. + * - " + - EQV + - Thermal equivalent strain. + * - EPDI + - X, Y, Z, XY, YZ, XZ + - Component diffusion strain. + * - " + - 1, 2, 3 + - Principal diffusion strain. + * - " + - INT + - Diffusion strain intensity. + * - " + - EQV + - Diffusion equivalent strain. + * - NL + - SEPL + - Equivalent stress (from stress-strain curve). + * - " + - SRAT + - Stress state ratio. + * - " + - HPRES + - Hydrostatic pressure. + * - " + - EPEQ + - Accumulated equivalent plastic strain. + * - " + - CREQ + - Accumulated equivalent creep strain. + * - " + - PSV + - Plastic state variable. + * - " + - PLWK + - Plastic work/volume. + * - TG + - X, Y, Z, SUM + - Component thermal gradient or vector sum. + * - TF + - X, Y, Z, SUM + - Component thermal flux or vector sum. + + ETABLE items are not supported for :ref:`esol` items. + + PAIR solution quantities are output on a per contact pair basis. GCN solution quantities are output + on a “per general contact section” basis. (See `Comparison of Pair-Based Contact and General Contact + `_ + :file:`Jobname.nlh` file represent a minimum or a maximum over the associated contact pair or + general contact surface, as detailed in the table below. + + .. _nlhist_tab_2: + + NLHIST - Valid Contact (PAIR or GCN) Item and Component Labels + ************************************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - CONT + - ELCN + - If >0, number of contact elements in contact. Other values are interpreted as follows: * 0 indicates the contact pair (or GCN surface) is in near-field contact status. * -1 indicates the contact pair (or GCN surface) is in far-field contact status. * -2 indicates that the contact pair (or GCN surface) is inactive ( symmetric to asymmetric contact ). + * - " + - ELST + - Number of contact elements in sticking contact status + * - " + - CNOS + - Maximum chattering level + * - " + - PENE + - Maximum penetration (or minimum gap) [ :ref:`nlhist_tab2note1` ] + * - " + - CLGP + - Maximum geometric gap + * - " + - SLID + - Maximum total sliding distance (algebraic sum) + * - " + - SLMX + - Maximum total sliding distance for closed contact in the current substep + * - " + - ESLI + - Maximum elastic slip distance + * - " + - KNMX + - Maximum normal contact stiffness + * - " + - KTMX + - Maximum tangential contact stiffness + * - " + - KNMN + - Minimum normal contact stiffness + * - " + - KTMN + - Minimum tangential contact stiffness + * - " + - PINB + - Maximum pinball radius + * - " + - PRES + - Maximum contact pressure + * - " + - SFRI + - Maximum frictional stress + * - " + - CNDP + - Average contact depth + * - " + - CLPE + - Maximum geometric penetration + * - " + - LGPE + - Number of contact points having too much penetration + * - " + - CAREA + - Contacting area + * - " + - NDMP + - Maximum contact damping pressure + * - " + - TDMP + - Maximum tangential contact damping stress + * - " + - GSMX + - Maximum total sliding distance ( GSLID ), including near-field + * - " + - GSMN + - Minimum total sliding distance ( GSLID ), including near-field + * - " + - FPSC + - Maximum normal fluid penetration pressure on contact surface + * - " + - FPST + - Maximum normal fluid penetration pressure on target surface + * - " + - WEAR + - Total volume lost due to wear for the contact pair (not available for general contact, ``Key`` = GCN ) + * - " + - CTEN + - Total strain energy due to contact constraint [ :ref:`nlhist_tab2note2` ] + * - " + - CFEN + - Total frictional dissipation energy [ :ref:`nlhist_tab2note2` ] + * - " + - CDEN + - Total contact stabilization energy [ :ref:`nlhist_tab2note2` ] + * - " + - CFNX + - Total force due to contact pressure - X component [ :ref:`nlhist_tab2note4` ] + * - " + - CFNY + - Total force due to contact pressure - Y component [ :ref:`nlhist_tab2note4` ] + * - " + - CFNZ + - Total force due to contact pressure - Z component [ :ref:`nlhist_tab2note4` ] [ :ref:`nlhist_tab2note5` ] + * - " + - CFSX + - Total force due to tangential stress - X component [ :ref:`nlhist_tab2note4` ] + * - " + - CFSY + - Total force due to tangential stress - Y component [ :ref:`nlhist_tab2note4` ] + * - " + - CFSZ + - Total force due to tangential stress - Z component [ :ref:`nlhist_tab2note4` ] [ :ref:`nlhist_tab2note5` ] + * - " + - CTRQ + - Maximum torque in an axisymmetric analysis with MU = 1.0 + * - " + - LGSL + - Number of contact points having too much sliding for small sliding contact + * - " + - NORM + - Pair-based force convergence norm [ :ref:`nlhist_tab2note3` ] + * - " + - CRIT + - Pair-based force convergence criterion [ :ref:`nlhist_tab2note3` ] + * - " + - FPTC + - Maximum tangential fluid penetration pressure on contact surface + * - " + - FPTT + - Maximum tangential fluid penetration pressure on target surface + + .. _nlhist_tab2note1: + + For PENE, a positive value indicates a penetration, and a negative value indicates a gap. If the + contact pair (or GCN surface) has a far-field contact status, penetration and gap are not available, + and the value stored for PENE is the current pinball radius. + + .. _nlhist_tab2note2: + + The pair-based dissipation energy (CFEN) and stabilization energy (CDEN) do not include + contributions from contact elements that are in far-field. The pair-based strain energy (CTEN) does + not include the frictional dissipation energy and stabilization energy; it only contains an elastic + recovery energy when the contact status changes from closed to open. + + .. _nlhist_tab2note3: + + The program uses a default tolerance value of 0.1 to calculate the pair-based force convergence norm + and pair-based force convergence criterion. This is not a check for local convergence. It is for + monitoring purposes only and is useful for nonlinear contact diagnostics. + + .. _nlhist_tab2note4: + + If the specified contact pair is a `rigid surface or force-distributed constraint + `_ + that includes stress stiffening effects, this quantity represents a total constraint force or moment + at the pilot node as shown below: + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + + .. _nlhist_tab2note5: + + For the case of 2D axisymmetric with torsion ( ``CONTA172`` with a ROTY DOF), CFNZ and CFSZ + represent moments along the Y direction. + + NLHIST - Valid Result Section (RSEC) Item and Component Labels + ************************************************************** + + .. flat-table:: + :header-rows: 1 + + * - Item + - Comp + - Description + * - REST + - SECF + - Total section force + * - " + - SECM + - Total section moment + * - " + - AXST + - Section axial stress + * - " + - BDST + - Section bending stress + * - " + - SPTX + - Section center X coordinate + * - " + - SPTY + - Section center Y coordinate + * - " + - SPTZ + - Section center Z coordinate + * - " + - THXY + - Rotation about local z + * - " + - THYZ + - Rotation about local x + * - " + - THZX + - Rotation about local y + """ command = f"NLHIST,{key},{name},{item},{comp},{node},{elem},{shell},{layer},{stop_value},{stop_cond}" return self.run(command, **kwargs) - def nlmesh(self, control="", val1="", val2="", val3="", val4="", **kwargs): - """Controls remeshing in nonlinear adaptivity. + def nlmesh(self, control: str = "", val1: str = "", val2: str = "", **kwargs): + r"""Controls remeshing in `nonlinear adaptivity + `_. - APDL Command: NLMESH + Mechanical APDL Command: `NLMESH `_ Parameters ---------- - control + control : str The mesh-quality control to adjust: - NANG - Specifies the surface facet dihedral angle threshold. Use this option to retain - source mesh geometry features. The dihedral angle is - defined by the angle between the normal vectors from two - neighboring surface facet sharing an edge. If the dihedral - angle is larger than the specified threshold, the edge is - treated as soft edge so that the new nodes are forced to - the edge. + * ``NLAY`` - The sculpting layer adjustment: + + ``VAL1`` - The number of sculpting layers, beginning with detected seed elements. Valid for 2D and + 3D analysis. + + * Default: ``VAL1`` = 10 for 2D analysis, ``VAL1`` = 2 for 3D analysis. + * For local (partial) remeshing, this option helps the remesher to detect remeshing regions from the + whole deformed model. + * Generally, a larger ``VAL1`` leads to larger remeshing regions and tends to unite isolated + multiple regions. A larger value also tends to result in better remeshing quality (and increases + mapping and solution overhead accordingly). + * Only elements with the same element and material properties as seed elements are included into the + remeshing regions. + * ``VAL1`` = 0 is not valid, as the remeshing regions would contain only the detected seed elements, + resulting in many small cavities within remeshing regions (especially if the specified mesh- + quality metric threshold ( :ref:`nladaptive` ) is relatively large). + + ``VAL2`` - Same as ``VAL1``, except that ``VAL1`` controls remeshing to remove distortion and + ``VAL2`` controls element refinement. Default: ``VAL2`` = 1 for 2D analysis, ``VAL2`` = 2 for 3D + analysis. + + Not used in a `NLAD-ETCHG analysis + `_. + + For more information about this control, see `Sculpting Layers Control + `_ + + * ``BDRA`` - The boundary angle threshold in degrees. Use this adjustment to retain geometry + features of the original (source) mesh. Valid for both 2D and 3D analysis. + + In a 3D analysis, this value is the dihedral angle (the angle between the normal vectors from two + neighboring surface facets). In a 2D analysis, this value is the 2D patch boundary edge normal + angle. If the edge angle or dihedral angle is larger than the specified threshold, the node shared + by 2D edges or edges shared by 3D facets are retained during remeshing. + + Valid values: 0 < ``VAL1`` < 80. + + Default for 2D analysis: ``VAL1`` = 10. Default for 3D analysis: ``VAL1`` = 15. + + Generally, a larger ``VAL1`` improves the quality of the new mesh (and may even repair local tiny + edges or facets of poor quality). Too large a value, however, may also smooth out some geometric + features, leading to slightly different results and possibly causing convergence issues in the + substeps immediately following remeshing. + + For more information about this control, see `Boundary-Angle and Edge-Angle Control + `_ + + * ``AEDG`` - The edge angle threshold in degrees. Valid for 3D analysis only. + + Use this control to split 3D patch segments. The edge angle is the angle between adjacent surface + segment edges sharing a node. If the edge angle is larger than the specified threshold (VAL1), the + segment splits and the node is automatically treated as a node to be retained. + + Default: ``VAL1`` = 10. + + Generally, a larger ``VAL1`` improves the quality of the new mesh, but may result in loss of feature + nodes. The effect is similar to that of boundary angles ( ``Control`` = BDRA). + + For more information about this control, see `Boundary-Angle and Edge-Angle Control + `_ + + * ``SRAT`` - The global sizing ratio. Valid for 2D and 3D analysis. + + ``VAL1`` - The global sizing ratio for remeshing. + + * Default: ``VAL1`` = 1.0. The default value results in the new mesh having a size similar to that + of the original mesh. + * Generally, set the value ( ``VAL1`` ) to >= 0.7. The model can be refined (< 1.0) or coarsened (> + 1.0) up to 3x depending on the mesh-sizing gradient and number of 3D elements, and approximately + 2x for 2D elements. - VAL1 is the dihedral angle threshold (in degrees) on concave surfaces. VAL2 is the dihedral angle threshold (in degrees) on convex surfaces. - Default: VAL1 = 15 and VAL2 = 15. + ``VAL2`` - Same as ``VAL1``, except that ``VAL1`` controls remeshing to remove distortion and + ``VAL2`` controls element refinement. Default: ``VAL2`` = 0.75. - When NLMESH,EXPL is issued, the VAL1 and VAL2 become the lower bounds of dihedral angles for mesh exploration. Use VAL3 and VAL4 to define the upper bounds of dihedral angles on concave and convex surfaces (respectively) for mesh exploration. - Generally, larger VAL1 and VAL2 values lead to better quality new meshes (and - may even repair local tiny facets of poor - quality); however, larger values may also smooth - out some geometric features, leading to slightly - different results and causing possible - convergence difficulty in the substeps - immediately following remeshing. + Not used in a `NLAD-ETCHG analysis + `_. - AEDG - Specifies the edge angle threshold (in degrees). Use this option to split patch - segments. The edge angle is the angle between adjacent - surface segment edges sharing a node. If the edge angle is - larger than the specified threshold (VAL1), the segment - splits and the node is automatically treated as a hard node - to be retained. + For more information about this control, see `Global Sizing Control + `_ - Default: VAL1 = 10. - Generally, larger VAL1 values improve the quality of the new mesh, but may - result in fewer feature nodes. The effect is - similar to that of dihedral angles. + * ``GRAD`` - Adjusts the new mesh-sizing gradient during remeshing. Valid for 2D and 3D analysis. - SRAT - Specifies the global sizing ratio for remeshing. + Valid values: ``VAL1`` = 0, 1, 2, or 3. Default: ``VAL1`` = 2 for 2D analysis, ``VAL1`` = 3 for 3D + analysis. - Generally, set the lower value (VAL1) to >= 0.7 and the upper value (VAL2) to <= 1.5. Within this range, the model can be refined (< 1.0) or coarsened (> 1.0) up to 3x depending on the number of elements (if performing a remesh of the entire model). - Default: VAL1 = 1.0. The default value results in the new mesh having a similar - size as that of the source mesh. + * ``VAL1`` = 0 -- The mesh-sizing gradient is not retained. The new mesh is uniform and has an + approximate average size on the entire remeshed domain(s), even if the original mesh has sizing + gradients. + * ``VAL1`` = 1 -- The new mesh follows the original mesh-sizing gradient to retain the element + averaged-edge length. This value tends to coarsen the mesh in the location of the distorted + elements during remeshing. + * ``VAL1`` = 2 -- The new mesh follows the sizing gradient of the original mesh, with additional + sizing compensation based on the element size change due to deformation during solution. This + value tends to refine the mesh at the location of the distorted elements, where the distortion may + have originated from deformation during solution. + * ``VAL1`` = 3 -- Similar to ``VAL1`` = 2, but assumes that perfect mesh quality is not required, + thus avoiding over-refinement of minor distorted regions. Valid for 3D analysis only. - NLAY - Specifies the number of sculpting layers beginning with detected seed elements. - This option helps to detect remeshing regions from whole - model. + For more information about this control, see. - Default: VAL1 = 2. - Generally, a larger VAL1 value leads to larger remeshing regions and tends to - unite isolated multiple regions. A larger value - also tends to result in better remeshing quality - (and increases mapping and solution overhead - accordingly). + * ``QTOL`` - The new mesh-acceptance tolerance ( ``PLANE182``, ``PLANE222``, ``SOLID187``, + ``SOLID227``, and ``SOLID285`` ). - VAL1 = 0 is not valid, as the remeshing regions would contain only detected seed elements, resulting in many small cavities within remeshing regions (especially if the specified skewness threshold (NLADAPTIVE) is relatively large). - When NLMESH,EXPL is issued, VAL1 becomes the lower bound of mesh exploration. - Use VAL2 to define the upper bound for mesh - exploration. + ``VAL1`` - Controls remeshing to remove distortion. Default: 0.05. - LSRT - Specifies the local sizing ratio threshold (VAL1). If the length of adjacent - segments over that of surface short segments exceeds the - specified threshold ratio, the neighboring segments are - candidates for local sizing to improve target mesh quality. + ``VAL2`` - Controls element refinement. Default: 0.5. - Use local sizing in cases where any of the following conditions exist: - Short edges significantly smaller than average + For ``PLANE182`` and ``PLANE222``, ``VAL2`` is the only valid option (for mesh refinement), and the + new mesh is accepted when ( MaxCornerAngleNew - MaxCornerAngleOld ) / MaxCornerAngleOld <= ``QTOL``. - Poor surface mesh (triangles) on top edges - Small surface patches composed of few triangles caused by small user-specified - dihedral angles. + For ``SOLID285``, the new mesh is accepted when ( SkewnessNew - SkewnessOld ) / SkewnessOld <= + ``QTOL``. - Valid values are VAL1 >= 1.0. Default: VAL1 = 1.0. - When NLMESH, EXPL is issued, VAL1 becomes the lower bound of mesh exploration. - Use VAL2 to define the upper bound for mesh - exploration. + For ``SOLID187`` and ``SOLID227``, the new mesh is accepted when, in addition to skewness, ( + JacobianOld - JacobianNew ) / JacobianOld <= ``QTOL``. - For more information about this control, see "Notes". - EXPL + The program uses both tolerance and mesh-quality parameters to determine whether or not a new mesh + is accepted. - Specifies the nonlinear mesh-exploration behavior. Mesh exploration consists of trying various mesh controls to obtain the best quality mesh during remeshing process. - For more information about this control, see "Notes". + Not used in a `NLAD-ETCHG analysis + `_. - LIST - Lists all defined advanced control parameters. + * ``REFA`` - The refinement algorithm adjustment ( ``PLANE182``, ``PLANE222``, and ``SOLID285`` ). Valid for 2D + and 3D analysis. - val1, val2, val3, val4 - Numerical input values that vary according to the specified Control - option. + ``VAL1`` - + + * SPLIT - Use mesh `splitting + `_ instead of + general remeshing. This is the only valid value. + + If not specified, mesh refinement occurs via general remeshing (except for ``PLANE183`` ). + + Not used in a `NLAD-ETCHG analysis + `_. + + * ``TCOR`` - Coordinate truncation adjustments for nodal locations of the meshes during remeshing. Valid for 2D + and 3D analysis. + + ``VAL1`` - + + * ON - Truncates the decimal value after the seventh position. Default behavior for ``PLANE182``, + ``PLANE222``, and ``SOLID285`` (augmented Lagrange and penalty contact formulations only). + * OFF - No truncation occurs on the decimal value. Default behavior for ``SOLID187`` and + ``SOLID227`` (all contact formulations), and ``PLANE182`` and ``PLANE222`` (Lagrange multiplier + contact formulation only). + * ``AGGR`` - Aggressive remeshing. Creates meshes with improved shape metrics. May change some global remeshing + control parameters applied by other :ref:`nlmesh` commands, and may increase remeshing time. Valid + for both 2D and 3D nonlinear adaptivity analysis. + + ``VAL1`` - + + * ON - Enable aggressive remeshing. + * OFF - Disable aggressive remeshing (default). + * ``ELSZ`` - Reduces the set of remeshable (seed) elements used for remeshing by filtering out + elements based on their size, preventing over- or under-refinement in the remeshing regions. Valid + only in `general remeshing + `_ + using an energy -, position-, or `contact + `_ + -based refinement criterion. + + ``Val1`` is a user-defined lower bound of the element size, and ``Val2`` is a user-defined upper + bound of the element size. If both are specified, seed elements selected via the specified criterion + are filtered out if their size is < ``Val1`` or > ``Val2``. If ``Val1`` is unspecified, only the + size check with ``Val2`` occurs. If ``Val2`` is unspecified, only the size check with ``Val1`` + occurs. + + * ``NSTR`` - Reduces the set of remeshable (seed) elements used for remeshing by filtering out elements based on + their (maximum) equivalent stress level, preventing over- or under-refinement in the remeshing + regions based on the stress state. Valid only in `general remeshing + `_ + using an energy -, position-, or `contact + `_ + -based refinement criterion. + + ``Val1`` is a user-defined lower bound of element equivalent stress, and ``Val2`` is a user-defined + upper bound of the element equivalent stress. If both are specified, seed elements selected by the + specified criterion are filtered out if their (maximum) equivalent stress is < ``Val1`` or > + ``Val2``. If ``Val1`` is unspecified, only the equivalent stress check with ``Val2`` occurs. If + ``Val2`` is unspecified, only the equivalent stress check with ``Val1`` occurs. + + **Important:** Before specifying this option, copy the integration-point results to the nodes ( :ref:`eresx`,NO). + + * ``NSTN`` - Reduces the set of remeshable (seed) elements used for remeshing by filtering out elements based on + their (maximum) equivalent strain level, preventing over- or under-refinement in the remeshing + regions based on the strain state. Valid only in `general remeshing + `_ + using an energy -, position-, or `contact + `_ + -based refinement criterion. + + ``Val1`` is a user-defined lower bound of the element equivalent strain, and ``Val2`` is a user- + defined upper bound of the element equivalent strain. If both are specified, seed elements selected + by the specified criterion are filtered out if their (maximum) equivalent strain is < ``Val1`` or > + ``Val2``. If ``Val1`` is unspecified, only the equivalent strain check with ``Val2`` occurs. If + ``Val2`` is unspecified then only the equivalent strain check with ``Val1`` occurs. + + **Important:** Before specifying this option, copy the integration-point results to the nodes ( :ref:`eresx`,NO). + + * ``LIST`` - Lists all mesh-quality control parameters. + + If ``VAL1`` has been specified for a given mesh control, the most recently specified value is + listed. If a value was not explicitly specified, the default value is listed (assuming that the + problem has been solved at least once). + + val1 : str + Numerical input value that varies according to the specified ``Control`` option. + + Valid for all ``Control`` options. Can be used when controlling remeshing for both distortion + removal and for element refinement. + + val2 : str + Numerical input value that varies according to the specified ``Control`` option. + + Valid only for these ``Control`` options: NLAY, SRAT, and QTOL. Also used for controlling + remeshing for element refinement. Notes ----- - NLMESH is a global control command enabling mesh-quality adjustments - for remeshing in nonlinear adaptivity. The command can be used when - components are associated with mesh-quality criteria (NLADAPTIVE with - Criterion = MESH). - - Issue the NLMESH command only in cases where advanced mesh-quality - control is desirable for remeshing in nonlinear adaptivity. The - settings specified by this command apply to all components having mesh- - quality-based criteria defined. - - Following are LSRT usage examples to help you determine a suitable - threshold value for the local sizing ratio: - - If the value is only slightly greater than the minimum (and default) - value of 1.0, local sizing is imposed on all segments. Recommended: - VAL1 > 1.1. - - If the value is large enough such that no neighboring segments have - lengths that would cause the threshold ratio to be exceeded, all - segments are treated as though local sizing is disabled. - - For mesh exploration (NLMESH,EXPL,VAL1): - - VAL1 = 0 -- The exception to the default behavior (no mesh exploration) - occurs when remeshing fails to create a mesh for the user-specified - NLMESH input parameters. In this case, mesh exploration is performed as - though VAL1 = 1, with default NANG upper bounds of 60,60 in order to - continue the solution, and the lower bounds being user-specified. - - VAL1 = 1 -- The NANG lower and upper bounds must be input; otherwise, - the command is ignored. The upper bound can be input for NLAY also, but - the exploration still triggers remeshings with the whole model as seed - elements. - - VAL1 = 2 -- The NANG lower and upper bounds must be input; otherwise, - the command is ignored. - - VAL1 = 3 -- An optional upper bound can be specified via LSRT. By - default, the upper bound is set to be 30 percent more than the (user- - specified) lower bound. - - Mesh exploration is needed only when it is difficult to obtain a good - quality mesh via standard remeshing. It is good practice to first try - less aggressive exploration with VAL1 = 1. + + .. _NLMESH_notes: + + :ref:`nlmesh` is a global control command enabling mesh-quality adjustments for remeshing in + `nonlinear adaptivity + `_. The command + can be used when components are associated with mesh-quality criteria ( :ref:`nladaptive` with + ``Criterion`` = MESH, or another criterion with mesh change through general refinement). + + Issue the :ref:`nlmesh` command only in cases where advanced mesh-quality control is desirable for + remeshing in nonlinear adaptivity. The control values specified apply to all components having mesh- + quality-based criteria defined, or components having mesh change through general refinement, and can + be modified at every load step during the nonlinear adaptive solution or when performing a restart + analysis. """ - command = f"NLMESH,{control},{val1},{val2},{val3},{val4}" + command = f"NLMESH,{control},{val1},{val2}" return self.run(command, **kwargs) - def nropt(self, option1="", option2="", optval="", **kwargs): - """Specifies the Newton-Raphson options in a static or full transient + def nropt(self, option1: str = "", option2: str = "", optval: str = "", **kwargs): + r"""Specifies the Newton-Raphson options in a static or full transient analysis. - APDL Command: NROPT - analysis. + Mechanical APDL Command: `NROPT `_ Parameters ---------- - option1 + option1 : str Option key: - AUTO - Let the program choose the option (default). + * ``AUTO`` - Let the program choose the option (default). - FULL - Use full Newton-Raphson. + * ``FULL`` - Use full Newton-Raphson. - MODI - Use modified Newton-Raphson. + * ``MODI`` - Use modified Newton-Raphson. - INIT - Use the previously computed matrix (initial-stiffness). + * ``INIT`` - Use the previously computed matrix (initial-stiffness). - UNSYM - Use full Newton-Raphson with unsymmetric matrices of elements where the - unsymmetric option exists. + * ``UNSYM`` - Use full Newton-Raphson with unsymmetric matrices of elements where the unsymmetric + option exists. - option2 + option2 : str Option key: - CRPL - When applicable in a static creep analysis, activates modified Newton-Raphson - with a creep-ratio limit. Valid only when Option1 = AUTO. + * ``CRPL`` - When applicable in a static creep analysis, activates modified Newton-Raphson with a + creep-ratio limit. Valid only when ``Option1`` = AUTO. + + optval : str + If ``Option2`` is blank, ``Optval`` is the Adaptive Descent Key ( ``Adptky`` ): + + * ``ON`` - Use adaptive descent (default if frictional contact exists). Explicit ON is valid only if + ``Option`` = FULL. - optval - If Option2 is blank, Optval is the Adaptive Descent Key (Adptky): + * ``OFF`` - Do not use adaptive descent (default in all other cases). - ON - Use adaptive descent (default if frictional contact exists). Explicit ON is - valid only if Option = FULL. + If ``Option2`` = CRPL, ``Optval`` is the creep ratio limit: - OFF - Do not use adaptive descent (default in all other cases). + * ``CRLIMIT`` - The creep ratio limit for use with the modified Newton-Raphson procedure. Valid only + when ``Option1`` = AUTO (default) and ``Option2`` = CRPL. Typically, this value should not exceed + 0.15 in order to make the modified Newton-Raphson solution converge efficiently. For more + information about the creep ratio limit, see the :ref:`cutcontrol` command. Notes ----- - The NROPT command specifies the Newton-Raphson option used to solve the - nonlinear equations in a static or full transient analysis. - - The automatic modified Newton-Raphson procedure with creep-ratio limit - control (NROPT,AUTO,CRPL,CRLIMIT) applies to static creep analysis - only. When the creep ratio is smaller than the value of the creep ratio - limit specified, the modified Newton-Raphson procedure is used. If - convergence difficulty occurs during solution, use the full Newton- - Raphson procedure. - - The command NROPT,UNSYM is also valid in a linear non-prestressed modal - analysis that is used to perform a brake squeal analysis. In this - special case, the command is used only to generate the unsymmetric - stiffness matrix; no Newton-Raphson iterations are performed. - - NROPT,MODI and NROPT,INIT are only applicable with the sparse solver - (EQSLV,SPARSE). Thermal analyses will always use full Newton-Raphson - irrespective of the Option1 value selected. - - See Newton-Raphson Option in the Structural Analysis Guide for more + + .. _NROPT_notes: + + The :ref:`nropt` command specifies the Newton-Raphson option used to solve the nonlinear equations + in a static or full transient analysis. + + The automatic modified Newton-Raphson procedure with creep-ratio limit control ( + :ref:`nropt`,AUTO,CRPL, ``CRLIMIT`` ) applies to static creep analysis only. When the creep ratio is + smaller than the value of the creep ratio limit specified, the modified Newton-Raphson procedure is + used. If convergence difficulty occurs during solution, use the full Newton-Raphson procedure. + + The command :ref:`nropt`,UNSYM is also valid in a linear non-prestressed modal analysis that is used + to perform a brake squeal analysis. In this special case, the command is used only to generate the + unsymmetric stiffness matrix; no Newton-Raphson iterations are performed. + + :ref:`nropt`,MODI and :ref:`nropt`,INIT are only applicable with the sparse solver ( + :ref:`eqslv`,SPARSE). Thermal analyses will always use full Newton-Raphson irrespective of the + ``Option1`` value selected. + + See Newton-Raphson Option in the `Structural Analysis Guide + `_ for more information. This command is also valid in PREP7. - Switching Between the Symmetric and Unsymmetric Option + **Switching Between the Symmetric and Unsymmetric Option** - Normally, switching from the symmetric Newton-Raphson option - (NROPT,FULL) to the unsymmetric option (NROPT,UNSYM) or from the - unsymmetric option to the symmetric option is allowed between load - steps within the same analysis type. This is applicable to linear and + Normally, switching from the symmetric Newton-Raphson option ( :ref:`nropt`,FULL) to the + unsymmetric option ( :ref:`nropt`,UNSYM) or from the unsymmetric option to the symmetric option is + allowed between load steps within the same analysis type. This is applicable to linear and nonlinear, static and full transient analyses. - Under the following circumstances, the solution could be slightly - different or inaccurate if you switch from symmetric to unsymmetric or - vice versa: - - The underlying elements or materials are unsymmetric by their - mathematical definition, and you switch from unsymmetric to symmetric. - - You change analysis types and also switch from symmetric to unsymmetric - (or vice versa) at the same time. This situation could result in - failures such as data corruption or a core dump and should therefore be - avoided. - - In some rare cases, switching between the symmetric and unsymmetric - options can cause a system core dump when reading/writing the .ESAV or - .OSAV file, and the analysis terminates. Typically, this happens when - the record length of the element nonlinear saved variables cannot be - altered between load steps by their mathematical definition. - - If all the elements and the material are symmetric by their - mathematical definition and you use the unsymmetric option, the - solution accuracy is the same as the symmetric option. However, the - analysis will run twice as slow as the symmetric case. - - If the static or full transient solution is used as the base analysis - for a linear perturbation, be aware that switching to the unsymmetric - Newton-Raphson option forces the program to use the UNSYM or DAMP - eigensolver in a downstream modal analysis, which may be more expensive - than symmetric modal analysis. + Under the following circumstances, the solution could be slightly different or inaccurate if you + switch from symmetric to unsymmetric or vice versa: + + * The underlying elements or materials are unsymmetric by their mathematical definition, and you + switch from unsymmetric to symmetric. + + * You change analysis types and also switch from symmetric to unsymmetric (or vise versa) at the + same time. This situation could result in failures such as data corruption or a core dump and + should therefore be avoided. + + * In some rare cases, switching between the symmetric and unsymmetric options can cause a system + core dump when reading/writing the :file:`.ESAV` or :file:`.OSAV` file, and the analysis + terminates. Typically, this happens when the record length of the element nonlinear saved + variables cannot be altered between load steps by their mathematical definition. + + If all the elements and the material are symmetric by their mathematical definition and you use the + unsymmetric option, the solution accuracy is the same as the symmetric option. However, the analysis + will run twice as slow as the symmetric case. + + In a static or full transient linear perturbation base analysis, be aware that if the unsymmetric + Newton-Raphson procedure is used, you must specify the UNSYM or DAMP eigensolver option in the + downstream modal analysis, which may be more expensive than symmetric modal analysis. """ command = f"NROPT,{option1},{option2},{optval}" return self.run(command, **kwargs) - def pred(self, sskey="", lskey="", **kwargs): - """Activates a predictor in a nonlinear analysis. + def pred(self, sskey: str = "", lskey: str = "", **kwargs): + r"""Activates a predictor in a nonlinear analysis. + + Mechanical APDL Command: `PRED `_ + + **Command default:** + + .. _PRED_default: + + The default command behavior is to use prediction ( ``Sskey`` = AUTO). The AUTO option chooses to + either use the linear predictor or to turn the predictor OFF. However, prediction does not occur if + one or more of these conditions exist: + + * Over prediction occurs due to a large residual force or excessive element distortion. - APDL Command: PRED + * You are mapping ( :ref:`mapsolve` ) variables to a new mesh during `rezoning + `_. + (Prediction does not occur for any :ref:`mapsolve` substeps, nor for the first substep + afterwards.) + + * You have steady-state analysis defined ( :ref:`sstate` ), and contact elements exist in the model. Parameters ---------- - sskey + sskey : str Substep predictor key: - OFF - No prediction occurs. + * ``AUTO`` - The program uses a predictor but, within certain exceptions, automatically switches + prediction off. This behavior is the default; see :ref:`PRED_default` for details. + + * ``OFF`` - No prediction occurs. - ON - Use a predictor on all substeps after the first. + * ``LINEAR (or ON)`` - Use the linear predictor on all substeps after the first. - AUTO - The program uses a predictor but, within certain - exceptions, automatically switches prediction - off. This behavior is the default; see "Command - Default" for details. + * ``QUADRATIC`` - Use the quadratic predictor on all substeps after the second. - lskey + lskey : str Load step predictor: - OFF - No prediction across load steps occurs. This is the - default behavior. + * ``OFF`` - No prediction across load steps occurs. This is the default behavior. - ON - Use a predictor also on the first substep of the load - step. (Sskey = ON is required.) + * ``ON`` - Use a predictor also on the first substep of the load step. ( ``Sskey`` = ON is + required.) Notes ----- - Activates a predictor in a nonlinear analysis on the - degree-of-freedom solution for the first equilibrium iteration - of each substep. - - When using the arc-length method (ARCLEN, ARCTRM), you cannot - issue the DOF solution predictor command (PRED), the automatic - time stepping command (AUTOTS), or the line search command - (LNSRCH). If you activate the arc-length method after you set - PRED, AUTOTS, or LNSRCH, a warning message appears. If you - elect to proceed with the arc-length method, the program - disables your DOF predictor, automatic time stepping, and line - search settings, and the time step size is controlled by the - arc- length method internally. - - When using step-applied loads, such as TUNIF, BFUNIF, etc., or - other types of non-monotonic loads, the predictor may - adversely affect the convergence. If the solution is + + .. _PRED_notes: + + Activates a predictor in a nonlinear analysis on the degree-of-freedom solution for the first + equilibrium iteration of each substep. + + When using the arc-length method ( :ref:`arclen`, :ref:`arctrm` ), you cannot issue the DOF solution + predictor command ( :ref:`pred` ), the automatic time stepping command ( :ref:`autots` ), or the + line search command ( :ref:`lnsrch` ). If you activate the arc-length method after you set + :ref:`pred`, :ref:`autots`, or :ref:`lnsrch`, a warning message appears. If you elect to proceed + with the arc-length method, the program disables your DOF predictor, automatic time stepping, and + line search settings, and the time step size is controlled by the arc-length method internally. + + When using step-applied loads, such as :ref:`tunif`, :ref:`bfunif`, etc., or other types of non- + monotonic loads, the predictor may adversely affect the convergence. If the solution is discontinuous, the predictor may need to be turned off. - When performing a nonlinear analysis involving large - rotations, the predictor may require using smaller substeps. + When performing a nonlinear analysis involving large rotations, the predictor may require using + smaller substeps. If the model has rotational degrees-of-freedom, the quadratic predictor could work + more efficiently than the linear predictor. This command is also valid in PREP7. """ command = f"PRED,{sskey},,{lskey}" return self.run(command, **kwargs) - def pstres(self, key="", **kwargs): - """Specifies whether prestress effects are calculated or included. + def pstres(self, key: str = "", **kwargs): + r"""Specifies whether prestress effects are calculated or included. - APDL Command: PSTRES + Mechanical APDL Command: `PSTRES `_ Parameters ---------- - key + key : str Prestress key: - OFF - Do not calculate (or include) prestress effects (default). + * ``OFF`` - Do not calculate (or include) prestress effects (default). - ON - Calculate (or include) prestress effects. + * ``ON`` - Calculate (or include) prestress effects. Notes ----- - The PSTRES command specifies whether or not prestress effects are to be - calculated or included. The command should be issued after the ANTYPE - command. - Prestress effects are calculated in a static or transient analysis for - inclusion in a buckling, modal, harmonic (Method = FULL), or - substructure generation analysis. If used in the solution processor - (/SOLU), this command is valid only within the first load step. + .. _PSTRES_notes: + + The :ref:`pstres` command specifies whether or not prestress effects are to be calculated or + included. The command should be issued after the :ref:`antype` command. + + Prestress effects are calculated in a static or transient analysis for inclusion in a buckling, + modal, harmonic (Method = FULL), or substructure generation analysis. If used in the solution + processor ( :ref:`slashsolu` ), this command is valid only within the first load step. - If you apply thermal body forces during a static analysis to calculate - prestress effects, do not delete the forces during any subsequent full - harmonic analyses. If you delete the thermal body forces, the thermal - prestress effects will not be included in the harmonic analysis. - Temperature loads used to define the thermal prestress will also be - used in the full harmonic analysis as sinusoidally time-varying - temperature loads. + If you apply thermal body forces during a static analysis to calculate prestress effects, do not + delete the forces during any subsequent full harmonic analyses. If you delete the thermal body + forces, the thermal prestress effects will not be included in the harmonic analysis. Temperature + loads used to define the thermal prestress will also be used in the full harmonic analysis as + sinusoidally time-varying temperature loads. - A prestress effect applied with non-follower loads resists rigid body - rotation of the model. For example, an unsupported beam with axial - tensile forces applied to both ends will have two nonzero rotational - rigid body modes. + A prestress effect applied with non-follower loads resists rigid body rotation of the model. For + example, an unsupported beam with axial tensile forces applied to both ends will have two nonzero + rotational rigid body modes. - If tabular loading (``*DIM,,TABLE``) was used in the prestress static - analysis step, the corresponding value of TIME will be used for tabular - evaluations in the modal analysis. + If tabular loading ( :ref:`dim`, TABLE ) was used in the prestress static analysis step, the + corresponding value of :ref:`time` will be used for tabular evaluations in the modal analysis. This command is also valid in PREP7. """ command = f"PSTRES,{key}" return self.run(command, **kwargs) + + def semiimplicit( + self, option: str = "", type_: str = "", value: str = "", **kwargs + ): + r"""Specifies parameters for a semi-implicit solution. + + Mechanical APDL Command: `SEMIIMPLICIT `_ + + Parameters + ---------- + option : str + Option to be performed: + + * ``ETOI`` - Criterion for transitioning from the semi-implicit solution phase to the implicit + solution phase. + + * ``MSCA`` - Selective mass scaling factor used during the semi-implicit solution phase. + + * ``SFAC`` - Safety factor for time incrementation used during the semi-implicit solution phase. + + * ``AUTS`` - Automatic time stepping and bisection controls used during the semi-implicit solution + phase. + + * ``BVIS`` - Bulk viscosity controls used during the semi-implicit solution phase. + + * ``EFRQ`` - Output and restart file frequency used during the semi-implicit solution phase. + + type_ : str + Additional input; varies depending on the ``Option`` value. See table below. + + value : str + Additional input; varies depending on the ``Option`` and ``Type`` values. See table below. + + Notes + ----- + + .. _SEMIIMPLICIT_notes: + + This command triggers a `semi-implicit solution scheme + `_ in which + the analysis transitions to a semi-implicit solution method when the implicit solution method fails + to converge. The command is valid only in the solution processor ( :ref:`slashsolu` ) and must be + defined before the first :ref:`solve` command. + + The :ref:`semiimplicit` command can be used in a restart, even if the base analysis did not include + the command. Therefore, a problem that failed in the implicit analysis can be restarted with this + command so that it can transition to the semi-implicit method and solve further. + + The :ref:`semiimplicit` command can overwrite the values on some commands, as described in the + following table. + + This command contains some tables and extra information which can be inspected in the original + documentation pointed above. + """ + command = f"SEMIIMPLICIT,{option},{type_},{value}" + return self.run(command, **kwargs) + + def soloption(self, option: str = "", type_: str = "", value: str = "", **kwargs): + r"""Specifies solution transition options. + + Mechanical APDL Command: `SOLOPTION `_ + + Parameters + ---------- + option : str + Transition option: + + * ``STOT`` - Use criterion for transitioning from a static solution to a transient dynamic solution. + + * ``TTOS`` - Use criterion for transitioning from a transient dynamic solution to a static solution. + + type_ : str + Additional input; varies depending on the ``Option`` value. See table below. + + value : str + Additional input; varies depending on the ``Option`` and ``Type`` values. See table below. + + Notes + ----- + + .. _SOLOPTION_notes: + + This command triggers an automatic transition from a static solution to a transient solution based + on the specified criterion. The command is valid only in the solution processor ( :ref:`slashsolu` ) + and must be defined either before the first :ref:`solve` command or during a restart analysis. + + If :ref:`soloption` is issued with no arguments specified, the static solution will transition to a + quasi-static transient solution if the static solution fails to converge (that is, + :ref:`soloption`,STOT,CONV,QUASI). + + :ref:`soloption` can be used in a restart even if the base analysis did not include the command. + Therefore, a problem that failed in the static analysis can be restarted using this command so that + it transitions to a transient solution and solves further. Material densities are required for the + transient solution, but they must be defined during the static solution since the restart framework + does not permit material density to be defined in the restart analysis. + + For more information on using :ref:`soloption`, see `Automatic Transition Between Static and + Transient Solutions + `_ + """ + command = f"SOLOPTION,{option},{type_},{value}" + return self.run(command, **kwargs) + + def ssopt( + self, + option: str = "", + par1: str = "", + par2: str = "", + par3: str = "", + par4: str = "", + par5: str = "", + **kwargs, + ): + r"""Defines a solution option for soil analysis. + + Mechanical APDL Command: `SSOPT `_ + + Parameters + ---------- + option : str + Solution option to define: + + * ``GEOSTATIC`` - Geostatic equilibrium step for soil analysis. + + * ``CONSOLIDATION`` - Consolidation step for soil analysis. + + * ``STOP`` - Stop condition for soil consolidation analysis. + + * ``SFSW`` - Specific weight load. + + par1 : str + Parameters for the specified ``Option``. + + par2 : str + Parameters for the specified ``Option``. + + par3 : str + Parameters for the specified ``Option``. + + par4 : str + Parameters for the specified ``Option``. + + par5 : str + Parameters for the specified ``Option``. + + Notes + ----- + **Valid ParValues for Each Option** + * ``Option = GEOSTATIC`` - No parameter values required. + + * ``Option = CONSOLIDATION`` - No parameter values required. + + * ``Option = STOP`` - ``Par1`` : + + * SSTATE -- The steady-state solution threshold of incremental pore pressure in a step. + * OFF -- Deactivate steady-state solution check. + + ``Par2`` : + + * Valid only when ``Par1`` = SSTATE. + * A positive value to define the maximum pore pressure increment in a step, or a negative value to + define the percentage of incremental pore pressure in a step to maximum pore pressure in the + solution. + + * ``Option = SFSW`` - ``Par1, Par2, Par3`` : + + * The specific weight load direction. ( Default : The -Y axis in the global coordinate system.) + + ``Par4`` : + + * OFF -- Ignore the specific bulk weight (default). + * ON -- Account for the specific bulk weight load. + + ``Par5`` : + + * OFF -- Ignores the fluid specific weight (default). + * ON -- Account for the fluid specific weight. + + .. _SSOPT_notes: + + The :ref:`ssopt` command defines solution options for soil analysis ( :ref:`antype`,SOIL) only. + """ + command = f"SSOPT,{option},{par1},{par2},{par3},{par4},{par5}" + return self.run(command, **kwargs) + + def sstif(self, key: str = "", **kwargs): + r"""Activates stress stiffness effects in a nonlinear analysis. + + Mechanical APDL Command: `SSTIF `_ + + Parameters + ---------- + key : str + Stress stiffening key: + + * ``OFF`` - No stress stiffening is included (default unless :ref:`nlgeom`,ON). + + * ``ON`` - Stress stiffening is included (default if :ref:`nlgeom`,ON). + + Notes + ----- + + .. _SSTIF_notes: + + Activates stress stiffness effects in a nonlinear analysis ( :ref:`antype`,STATIC or TRANS). (The + :ref:`pstres` command also controls the generation of the stress stiffness matrix and therefore + should not be used in conjunction with :ref:`sstif`.) If used within the solution processor, this + command is valid only within the first load step. + + When :ref:`nlgeom` is ON, :ref:`sstif` defaults to ON. This normally forms all of the consistent + tangent matrix. However, for some special nonlinear cases, this can lead to divergence caused by + some elements which do not provide a complete consistent tangent (notably, elements outside the 18 + ``x`` family). In such a case, Ansys, Inc. recommends issuing an :ref:`sstif`,OFF command + to achieve convergence. For `current-technology elements + `_, + setting :ref:`sstif`,OFF when :ref:`nlgeom` is ON has no effect (because stress stiffness effects + are always included). + + This command is also valid in PREP7. + + .. warning:: + + This command is archived in the latest version of the software. + + """ + command = f"SSTIF,{key}" + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/commands.py b/src/ansys/mapdl/core/commands.py index 2f17a7705e6..b60be5db17c 100644 --- a/src/ansys/mapdl/core/commands.py +++ b/src/ansys/mapdl/core/commands.py @@ -479,19 +479,12 @@ class SolutionCommands( solution.fe_constraints.FeConstraints, solution.fe_forces.FeForces, solution.fe_surface_loads.FeSurfaceLoads, - solution.gap_conditions.GapConditions, solution.inertia.Inertia, solution.load_step_operations.LoadStepOperations, solution.load_step_options.LoadStepOptions, - solution.master_dof.MasterDOF, - solution.miscellaneous_loads.MiscellaneousLoads, - solution.multi_field_solver_convergence_controls.MultiFieldConvergenceControls, - solution.multi_field_solver_definition_commands.MultiFieldSolverDefinitionCommands, - solution.multi_field_solver_global_controls.MultiFieldSolverGlobalControls, - solution.multi_field_solver_interface_mapping.MultiFieldSolverInterfaceMapping, - solution.multi_field_solver_load_transfer.MultiFieldSolverLoadTransfer, - solution.multi_field_solver_time_controls.MultiFieldSolverTimeControls, - solution.nonlinear_options.NonLinearOptions, + solution.master_dof.MasterDof, + solution.misc_loads.MiscLoads, + solution.nonlinear_options.NonlinearOptions, solution.ocean.Ocean, solution.radiosity.Radiosity, solution.rezoning.Rezoning,