diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e1bdd5c6e3..db0179e0f3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -56,12 +56,12 @@ repos: hooks: - id: flake8 -# - repo: https://github.com/codespell-project/codespell -# rev: v2.3.0 -# hooks: -# - id: codespell -# args: ["--toml", "pyproject.toml"] -# additional_dependencies: ["tomli"] +- repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + args: ["--toml", "pyproject.toml"] + additional_dependencies: ["tomli"] # - repo: https://github.com/pycqa/pydocstyle # rev: 6.1.1 diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 0d27d17331..8ea113b8f0 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -70,6 +70,7 @@ emiss env Eser ethernet +Euclidian extrem FEMs filname @@ -86,6 +87,7 @@ hostname HTML Image[Mm]agick imagin +imbedded importlib ist Julia @@ -118,6 +120,8 @@ NumPy onefile optiSLang parm +ParY +pary perf performant PMLs diff --git a/src/ansys/mapdl/core/_commands/apdl/abbreviations.py b/src/ansys/mapdl/core/_commands/apdl/abbreviations.py index 86cb203598..66bb8f9d7b 100644 --- a/src/ansys/mapdl/core/_commands/apdl/abbreviations.py +++ b/src/ansys/mapdl/core/_commands/apdl/abbreviations.py @@ -23,38 +23,49 @@ class Abbreviations: - def abbr(self, abbr="", string="", **kwargs): - r"""Defines an abbreviation. + def ucmd(self, cmd: str = "", srnum: str = "", **kwargs): + r"""Assigns a user-defined command name. - Mechanical APDL Command: `\*ABBR `_ + Mechanical APDL Command: `/UCMD `_ Parameters ---------- - abbr : str - The abbreviation (up to 8 alphanumeric characters) used to represent the string ``String`` . If - ``Abbr`` is the same as an existing Mechanical APDL command, the abbreviation overrides. Avoid using an - ``Abbr`` which is the same as an Mechanical APDL command. + cmd : str + User-defined command name. Only the first four characters are significant. Must not conflict + with any Mechanical APDL command name or any user unknown-command macro name. - string : str - String of characters (60 maximum) represented by ``Abbr`` . Cannot include a $ or any of the - commands :ref:`c`, :ref:`com`, :ref:`gopr`, :ref:`nopr`, :ref:`quit`, :ref:`ui`, or - :ref:`end` . Parameter names and commands of the :ref:`do` and Use the :ref:`if` groups may not - be abbreviated. If ``String`` is blank, the abbreviation is deleted. To abbreviate multiple - commands, create an "unknown command" macro or define ``String`` to execute a macro file ( - :ref:`use` ) containing the desired commands. + srnum : str + User subroutine number (1 to 10) programmed for this command. For example, the command + :ref:`ucmd` ,MYCMD,3 will execute subroutine USER03 whenever the command MYCMD is entered. Use a + blank command name to disassociate ``SRNUM`` from its command. For example, :ref:`ucmd` ,,3 + removes MYCMD as a command. Notes ----- - Once the abbreviation ``Abbr`` is defined, you can issue it at the beginning of a command line and follow it with a blank (or with a comma and appended data), and the program will substitute the string ``String`` for ``Abbr`` as the line is executed. Up to 100 abbreviations may exist at any time and are available throughout the program. Abbreviations may be redefined or deleted at any time. - - Use :ref:`starstatus` to display the current list of abbreviations. For abbreviations repeated with :ref:`repeat`, substitution occurs before the repeat increments are applied. There are a number of abbreviations that are predefined by the program (these can be deleted by using the blank ``String`` option described above). Note that ``String`` will be written to the ``File.LOG`` . - - This command is valid in any processor. + Assigns a user-defined command name to a user-programmable (system-dependent) subroutine. This + feature allows user-defined commands to be programmed into Mechanical APDL. Once programmed, this command + can be input to the program like other commands, and can also be included in the Mechanical APDL start-up + file. Up to 10 subroutines are available for user-defined commands (USER01 to USER10). You must + have system permission, system access, and knowledge to write, compile, and link the appropriate + subprocessors into Mechanical APDL at your site. All routines should be written in FORTRAN. For more + information about FORTRAN compilers, refer to either the `Ansys, Inc. Windows Installation Guide `_ or the `Ansys, Inc. Linux Installation Guide `_ for + details specific to your platform or operating system. The USER01 routine is commented and should + be listed from the distribution media (system dependent) for more details. Issue :ref:`ucmd` ,STAT + to list all user-defined command names. Because a user-programmed command is a nonstandard use of + the program, the verification of any Mechanical APDL run incorporating these commands is your + responsibility. In any contact with Mechanical APDL customer support regarding the performance of a custom + version of Mechanical APDL, explicitly state that a user-programmable feature has been used. See `User- + Programmable Features (UPFs) + `_ + `Guide to User-Programmable Features + `_ + See :ref:`ulib` for another way of defining user commands. This command is valid only at the Begin + Level. """ - command = f"*ABBR,{abbr},{string}" + command = f"/UCMD,{cmd},{srnum}" return self.run(command, **kwargs) - def abbres(self, lab="", **kwargs): + def abbres(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): r"""Reads abbreviations from a coded file. Mechanical APDL Command: `ABBRES `_ @@ -64,94 +75,86 @@ def abbres(self, lab="", **kwargs): lab : str Label that specifies the read operation: - * ``NEW`` - Replace current abbreviation set with these abbreviations (default). - - * ``CHANGE`` - Extend current abbreviation set with these abbreviations, replacing any of - the - same name that already exist. + * ``NEW`` - Replace current abbreviation set with these abbreviations (default). + * ``CHANGE`` - Extend current abbreviation set with these abbreviations, replacing any of the same + name that already exist. fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - The file name defaults to ``Jobname`` . + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. The file name defaults to ``Jobname``. ext : str - Filename extension (eight-character maximum). - The extension defaults to ABBR if ``Fname`` is blank. + Filename extension (eight-character maximum). The extension defaults to ABBR if ``Fname`` is blank. Notes ----- - The abbreviation file may have been written with the :ref:`abbsav` command. Do not issue :ref:`abbres` ,NEW while inside an executing abbreviation. Doing so will cause all data for the executing abbreviation to be deleted. - - This command is valid in any processor. + The abbreviation file may have been written with the :ref:`abbsav` command. Do not issue + :ref:`abbres` ,NEW while inside an executing abbreviation. Doing so will cause all data for the + executing abbreviation to be deleted. This command is valid in any processor. """ - command = f"ABBRES,{lab}" + command = f"ABBRES,{lab},{fname},{ext}" return self.run(command, **kwargs) - def abbsav(self, lab="", **kwargs): - r"""Writes the current abbreviation set to a coded file. + def abbr(self, abbr: str = "", string: str = "", **kwargs): + r"""Defines an abbreviation. - Mechanical APDL Command: `ABBSAV `_ + Mechanical APDL Command: `\*ABBR `_ Parameters ---------- - lab : str - Label that specifies the write operation: - - * ``ALL`` - Write all abbreviations (default). - - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - The file name defaults to ``Jobname`` . + abbr : str + The abbreviation (up to 8 alphanumeric characters) used to represent the string ``String``. If + ``Abbr`` is the same as an existing Mechanical APDL command, the abbreviation overrides. Avoid using an + ``Abbr`` which is the same as an Mechanical APDL command. - ext : str - Filename extension (eight-character maximum). - The extension defaults to ABBR if ``Fname`` is blank. + string : str + String of characters (60 maximum) represented by ``Abbr``. Cannot include a $ or any of the + commands :ref:`c`, :ref:`com`, :ref:`gopr`, :ref:`nopr`, :ref:`quit`, :ref:`ui`, or + :ref:`end`. Parameter names and commands of the :ref:`do` and Use the :ref:`if` groups may not + be abbreviated. If ``String`` is blank, the abbreviation is deleted. To abbreviate multiple + commands, create an "unknown command" macro or define ``String`` to execute a macro file ( + :ref:`use` ) containing the desired commands. Notes ----- - Existing abbreviations on this file, if any, will be overwritten. The abbreviation file may be read with the :ref:`abbres` command. - + Once the abbreviation ``Abbr`` is defined, you can issue it at the beginning of a command line and + follow it with a blank (or with a comma and appended data), and the program will substitute the + string ``String`` for ``Abbr`` as the line is executed. Up to 100 abbreviations may exist at any + time and are available throughout the program. Abbreviations may be redefined or deleted at any + time. Use :ref:`starstatus` to display the current list of abbreviations. For abbreviations + repeated with :ref:`repeat`, substitution occurs before the repeat increments are applied. There + are a number of abbreviations that are predefined by the program (these can be deleted by using the + blank ``String`` option described above). Note that ``String`` will be written to the ``File.LOG``. This command is valid in any processor. """ - command = f"ABBSAV,{lab}" + command = f"*ABBR,{abbr},{string}" return self.run(command, **kwargs) - def ucmd(self, cmd="", srnum="", **kwargs): - r"""Assigns a user-defined command name. + def abbsav(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes the current abbreviation set to a coded file. - Mechanical APDL Command: `/UCMD `_ + Mechanical APDL Command: `ABBSAV `_ Parameters ---------- - cmd : str - User-defined command name. Only the first four characters are significant. Must not conflict - with any Mechanical APDL command name or any user unknown-command macro name. - - srnum : str - User subroutine number (1 to 10) programmed for this command. For example, the command - :ref:`ucmd` ,MYCMD,3 will execute subroutine USER03 whenever the command MYCMD is entered. Use a - blank command name to disassociate ``SRNUM`` from its command. For example, :ref:`ucmd` ,,3 - removes MYCMD as a command. - - Notes - ----- - Assigns a user-defined command name to a user-programmable (system-dependent) subroutine. This feature allows user-defined commands to be programmed into Mechanical APDL. Once programmed, this command can be input to the program like other commands, and can also be included in the Mechanical APDL start-up file. - - Up to 10 subroutines are available for user-defined commands (USER01 to USER10). You must have system permission, system access, and knowledge to write, compile, and link the appropriate subprocessors into Mechanical APDL at your site. - - All routines should be written in FORTRAN. For more information about FORTRAN compilers, refer to either the `Ansys, Inc. Windows Installation Guide `_ or the `Ansys, Inc. Linux Installation Guide `_ for details specific to your platform or operating system. - - The USER01 routine is commented and should be listed from the distribution media (system dependent) for more details. - - Issue :ref:`ucmd` ,STAT to list all user-defined command names. + lab : str + Label that specifies the write operation: - Because a user-programmed command is a nonstandard use of the program, the verification of any Mechanical APDL run incorporating these commands is your responsibility. In any contact with Mechanical APDL customer support regarding the performance of a custom version of Mechanical APDL, explicitly state that a user-programmable feature has been used. + * ``ALL`` - Write all abbreviations (default). - See `User-Programmable Features (UPFs) `_ `Guide to User-Programmable Features `_ + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. The file name defaults to ``Jobname``. - See :ref:`ulib` for another way of defining user commands. + ext : str + Filename extension (eight-character maximum). The extension defaults to ABBR if ``Fname`` is blank. - This command is valid only at the Begin Level. + Notes + ----- + Existing abbreviations on this file, if any, will be overwritten. The abbreviation file may be read + with the :ref:`abbres` command. This command is valid in any processor. """ - command = f"/UCMD,{cmd},{srnum}" + command = f"ABBSAV,{lab},{fname},{ext}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/array_parameters.py b/src/ansys/mapdl/core/_commands/apdl/array_parameters.py index ab5a79405a..ca5380ad5f 100644 --- a/src/ansys/mapdl/core/_commands/apdl/array_parameters.py +++ b/src/ansys/mapdl/core/_commands/apdl/array_parameters.py @@ -23,130 +23,133 @@ class ArrayParameters: - def directory(self, strarray="", filename="", ext="", dir="", **kwargs): - r"""Put the file names in the current directory into a string parameter array. + def mfun(self, parr: str = "", func: str = "", par1: str = "", **kwargs): + r"""Copies or transposes an array parameter matrix. - Mechanical APDL Command: `/DIRECTORY `_ + Mechanical APDL Command: `\*MFUN `_ Parameters ---------- - strarray : str - Name of the string array parameter which will hold the returned values. String array parameters - are similar to character arrays, but each array element can be as long as 128 characters. If the - string parameter does not exist, it will be created. The array will be created as: - \*DIM,StrArray,STRING,64,2,numFileName + parr : str + The name of the resulting array parameter matrix. See :ref:`starset` for name restrictions. - filename : str - File name (64 characters maximum). Only files matching this name will be returned. The - ``FileName`` ALL may match any file name. + func : str + Copy or transpose function: - ext : str - File name extension (8 characters maximum). Only files with an extension matching this name will - be returned. A blank or ALL will match any extension. + * ``COPY`` - ``Par1`` is copied to ``ParR`` + * ``TRAN`` - ``Par1`` is transposed to ``ParR``. Rows (m) and columns (n) of ``Par1`` matrix are + transposed to resulting ``ParR`` matrix of shape (n,m). - directory : str - The directory in which the files reside. The default is the current working directory. + par1 : str + Array parameter matrix input to the operation. Notes ----- - The :ref:`directory` command gets the file names in the current directory and puts them into a string parameter array. Each file will be included in the array as a name-extension pair. + Operates on one input array parameter matrix and produces one output array parameter matrix + according to: ``ParR`` = f( ``Par1`` ) where the function (f) is either a copy or transpose, as + described above. Functions are based on the standard FORTRAN definitions where possible. ``ParR`` + may be the same as ``Par1``. Starting array element numbers must be defined for each array parameter + matrix if it does not start at the first location. For example, :ref:`mfun` ,A(1,5),COPY,B(2,3) + copies matrix B (starting at element (2,3)) to matrix A (starting at element (1,5)). The diagonal + corner elements for each submatrix must be defined: the upper left corner by the array starting + element (on this command), the lower right corner by the current values from the :ref:`vcol` and + :ref:`vlen` commands. The default values are the (1,1) element and the last element in the matrix. + No operations progress across matrix planes (in the 3rd dimension). Absolute values and scale + factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( + :ref:`vcum` ). Array elements should not be skipped with the :ref:`vmask` and the ``NINC`` value of + the :ref:`vlen` specifications. The number of rows ( :ref:`vlen` ) applies to the ``Par1`` array. + See the :ref:`voper` command for details. This command is valid in any processor. """ - command = f"/DIRECTORY,{strarray},{filename},{ext},{dir}" + command = f"*MFUN,{parr},{func},{par1}" return self.run(command, **kwargs) - def mfouri(self, oper="", coeff="", mode="", isym="", theta="", curve="", **kwargs): - r"""Calculates the coefficients for, or evaluates, a Fourier series. + def mwrite( + self, + parr: str = "", + fname: str = "", + ext: str = "", + label: str = "", + n1: str = "", + n2: str = "", + n3: str = "", + **kwargs, + ): + r"""Writes a matrix to a file in a formatted sequence. - Mechanical APDL Command: `\*MFOURI `_ + Mechanical APDL Command: `\*MWRITE `_ Parameters ---------- - oper : str - Type of Fourier operation: - - * ``FIT`` - Calculate Fourier coefficients ``COEFF`` from ``MODE``, ``ISYM``, ``THETA``, - and - ``CURVE`` . - - * ``EVAL`` - Evaluate the Fourier curve ``CURVE`` from ``COEFF``, ``MODE``, ``ISYM`` and - ``THETA`` - - coeff : str - Name of the array parameter vector containing the Fourier coefficients (calculated if ``Oper`` = - FIT, required as input if ``Oper`` = EVAL). See :ref:`starset` for name restrictions. - - mode : str - Name of the array parameter vector containing the mode numbers of the desired Fourier terms. - - isym : str - Name of the array parameter vector containing the symmetry key for the corresponding Fourier - terms. The vector should contain keys for each term as follows: - - * ``0 or 1`` - Symmetric (cosine) term - - * ``-1`` - Antisymmetric (sine) term. - - theta, curve : str - Names of the array parameter vectors containing the theta vs. curve description, respectively. - Theta values should be input in degrees. If ``Oper`` = FIT, one curve value should be supplied - with each theta value. If ``Oper`` = EVAL, one curve value will be calculated for each theta - value. - - Notes - ----- - Calculates the coefficients of a Fourier series for a given curve, or evaluates the Fourier curve from the given (or previously calculated) coefficients. The lengths of the ``COEFF``, ``MODE``, and ``ISYM`` vectors must be the same--typically two times the number of modes desired, since two terms (sine and cosine) are generally required for each mode. The lengths of the ``CURVE`` and ``THETA`` vectors should be the same or the smaller of the two will be used. There should be a sufficient number of points to adequately define the curve--at least two times the number of coefficients. A starting array element number (1) must be defined for each array parameter vector. The vector specifications :ref:`vlen`, :ref:`vcol`, :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` do not apply to this command. Array elements should not be skipped with the :ref:`vmask` and the ``NINC`` value of the :ref:`vlen` specifications. The vector being calculated ( ``COEFF`` if ``Oper`` is FIT, or ``CURVE`` if ``Oper`` is EVAL) must exist as a dimensioned array ( :ref:`dim` ). - - This command is valid in any processor. - """ - command = f"*MFOURI,{oper},{coeff},{mode},{isym},{theta},{curve}" - return self.run(command, **kwargs) - - def mfun(self, parr="", func="", par1="", **kwargs): - r"""Copies or transposes an array parameter matrix. + parr : str + The name of the array parameter. See :ref:`starset` for name restrictions. - Mechanical APDL Command: `\*MFUN `_ + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. If the file name fields are left blank, the default file is the current output + file. - Parameters - ---------- - parr : str - The name of the resulting array parameter matrix. See :ref:`starset` for name restrictions. + ext : str + Filename extension (eight-character maximum). - func : str - Copy or transpose function: + label : str + Can use a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (JIK). - * ``COPY`` - ``Par1`` is copied to ``ParR`` + n1 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. - * ``TRAN`` - ``Par1`` is transposed to ``ParR`` . Rows (m) and columns (n) of ``Par1`` - matrix - are transposed to resulting ``ParR`` matrix of shape (n,m). + n2 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. - par1 : str - Array parameter matrix input to the operation. + n3 : str + Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` + ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. Notes ----- - Operates on one input array parameter matrix and produces one output array parameter matrix according to: ``ParR`` = f( ``Par1`` ) - - where the function (f) is either a copy or transpose, as described above. - - Functions are based on the standard FORTRAN definitions where possible. ``ParR`` may be the same as ``Par1`` . Starting array element numbers must be defined for each array parameter matrix if it does not start at the first location. For example, :ref:`mfun` ,A(1,5),COPY,B(2,3) copies matrix B (starting at element (2,3)) to matrix A (starting at element (1,5)). The diagonal corner elements for each submatrix must be defined: the upper left corner by the array starting element (on this command), the lower right corner by the current values from the :ref:`vcol` and :ref:`vlen` commands. The default values are the (1,1) element and the last element in the matrix. No operations progress across matrix planes (in the 3rd dimension). Absolute values and scale factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Array elements should not be skipped with the :ref:`vmask` and the ``NINC`` value of the :ref:`vlen` specifications. The number of rows ( :ref:`vlen` ) applies to the ``Par1`` array. See the :ref:`voper` command for details. - - This command is valid in any processor. + Writes a matrix or vector to a specified file in a formatted sequence. You can also use the + :ref:`vwrite` command to write data to a specified file. Both commands contain format descriptors on + the line immediately following the command. The format descriptors can be in either FORTRAN or C + format. FORTRAN format descriptors are enclosed in parentheses. They must immediately follow the + :ref:`mwrite` command on a separate line of the same input file. The word FORMAT should not be + included. The format must specify the number of fields to be written per line, the field width, the + placement of the decimal point, etc. There should be one field descriptor for each data item + written. The write operation uses the available system FORTRAN FORMAT conventions (see your system + FORTRAN manual). Any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and + character format (A) may be used. Integer (I) and list-directed (\*) descriptors may `not` be used. + Text may be included in the format as a quoted string. `The FORTRAN descriptor must be enclosed in + parentheses` and the format must not exceed 80 characters (including parentheses). The "C" format + descriptors are used if the first character of the format descriptor line is not a left parenthesis. + "C" format descriptors may be up to 80 characters long, consisting of text strings and predefined + "data descriptors" between the strings where numeric or alphanumeric character data are to be + inserted. The normal descriptors are %I for integer data, %G for double precision data, %C for + alphanumeric character data, and %/ for a line break. There must be one data descriptor for each + specified value in the order of the specified values. The enhanced formats described in :ref:`msg` + can also be used. The starting array element number must be defined. Looping continues in the + directions indicated by the Label argument. The number of loops and loop skipping may also be + controlled via :ref:`vlen` and :ref:`vmask`, which work in the ``n2`` direction (by row on the + output file), and by :ref:`vcol`, which works in the ``n1`` direction (by column in the output + file). The vector specifications :ref:`vabs` and :ref:`vfact` apply to this command, while + :ref:`vcum` does not apply to this command. See :ref:`voper` for details. If you are in the GUI, the + :ref:`mwrite` command must be contained in an externally prepared file and read into Mechanical APDL (that + is, :ref:`use`, :ref:`input`, etc.). This command is valid in any processor. """ - command = f"*MFUN,{parr},{func},{par1}" + command = f"*MWRITE,{parr},{fname},{ext},{label},{n1},{n2},{n3}" return self.run(command, **kwargs) def moper( self, - parr="", - par1="", - oper="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", + parr: str = "", + par1: str = "", + oper: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", **kwargs, ): r"""Performs matrix operations on array parameter matrices. @@ -162,227 +165,207 @@ def moper( First array parameter matrix input to the operation. oper : str - Matrix operations. Usage of the ``Val1`` through ``Val6`` arguments varies for each operation, - as described below: - - * ``INVERT`` - ( :ref:`moper`, ``ParR``, ``Par1``, INVERT) - - Square matrix invert: Inverts the `n` x `n` matrix in `Par1` into `ParR` . The matrix must - be - well conditioned. - - Non-independent or ill-conditioned equations can cause erroneous results. - - For large matrices, use the APDL Math operation :ref:`lsfactor` for efficiency (see `APDL - Math - `_ - - * ``MULT`` - ( :ref:`moper`, ``ParR``, ``Par1``, MULT, ``Par2`` ) - - Matrix multiply: Multiplies ``Par1`` by ``Par2`` . The number of rows of ``Par2`` must equal - the - number of columns of ``Par1`` for the operation. If ``Par2`` is input with a number of rows - - greater than the number of columns of ``Par1``, matrices are still multiplied. However, the + Matrix operations. Usage of the ``Val1`` through ``Val6`` arguments varies for each operation, as described below: + + * ``INVERT`` - ( :ref:`moper`, ``ParR``, ``Par1``, INVERT) Square matrix invert: Inverts the `n` + x `n` matrix in `Par1` into `ParR`. The matrix must be well conditioned. Non-independent or ill- + conditioned equations can cause erroneous results. For large matrices, use the APDL Math + operation :ref:`lsfactor` for efficiency (see `APDL Math + `_ + * ``MULT`` - ( :ref:`moper`, ``ParR``, ``Par1``, MULT, ``Par2`` ) Matrix multiply: Multiplies + ``Par1`` by ``Par2``. The number of rows of ``Par2`` must equal the number of columns of ``Par1`` + for the operation. If ``Par2`` is input with a number of rows greater than the number of columns + of ``Par1``, matrices are still multiplied. However, the operation only uses a number of rows of + ``Par2`` equal to the number of columns of ``Par1``. + * ``COVAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, COVAR, ``Par2`` ) Covariance: The measure of + association between columns of the ``Par1`` input matrix. ``Par1`` of size m runs (rows) by n data + (columns) is first processed to produce a row vector containing the mean of each column, which is + transposed to the output column vector ``Par2`` of n array elements. The ``Par1`` and ``Par2`` + operation then produces ``ParR``, a resulting n x n matrix of covariances (with the variances as + the diagonal terms). + * ``CORR`` - ( :ref:`moper`, ``ParR``, ``Par1``, CORR, ``Par2`` ) Correlation: The correlation + coefficient between columns of the ``Par1`` input matrix. ``Par1`` of size m runs (rows) by n data + (columns) is first processed to produce a row vector containing the mean of each column, which is + then transposed to the output column vector ``Par2`` of n array elements. The ``Par1`` and + ``Par2`` operation then produces ``ParR``, a resulting `n` x n matrix of correlation coefficients + (with a value of 1.0 for the diagonal terms). + * ``SOLV`` - ( :ref:`moper`, ``ParR``, ``Par1``, SOLV, ``Par2`` ) Solution of simultaneous + equations: Solves the set of ``n`` equations of ``n`` terms of the form a n1 x 1 + a n2 x 2 + + :sup:`...` + a nn x n = b n where ``Par1`` contains the matrix of a-coefficients, ``Par2`` + contains the vector(s) of b-values, and ``ParR`` contains the vector(s) of x-results. ``Par1`` + must be a square matrix. The equations must be linear, independent, and well conditioned. Non- + independent or ill-conditioned equations can cause erroneous results. For large matrices, use the + APDL Math operation :ref:`lsfactor` for efficiency (see `APDL Math + `_ + * ``SORT`` - ( :ref:`moper`, ``ParR``, ``Par1``, SORT, ``Par2``, ``n1``, ``n2``, ``n3`` ) + Matrix sort: Sorts the columns of matrix ``Par1`` according to sort vector ``Par2`` and places the + result back into ``Par1``. Rows of ``Par1`` are moved to the corresponding positions indicated by + the values of ``Par2``. ``Par2`` may be a column of ``Par1`` (in which case it will also be + reordered). Alternatively, you may specify the column of ``Par1`` to sort using ``n1`` (leaving + ``Par2`` blank). A secondary sort can be specified by column ``n2``, and a third sort using + column ``n3``. ``ParR`` is the vector of initial row positions (the permutation vector). Sorting + ``Par1`` according to ``ParR`` should reproduce the initial ordering. + * ``NNEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, NNEAR, ``Toler`` ) Nearest Node: Finds the + nodes nearest to the given set of points in ``Par1``, where ``Par1`` is an `n` x 3 array of + coordinate locations. ``ParR`` is a vector of the nearest selected nodes, or 0 if no nodes are + nearer than ``Toler``. ``Toler`` defaults to 1 and is limited to the maximum model size. + * ``ENEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, ENEAR, ``Toler`` ) Nearest Element: Finds the + elements nearest to the given set of points in ``Par1``, where ``Par1`` is an `n` x 3 array of + coordinate locations. ``ParR`` is a vector of the nearest selected elements, or 0 if no element + centroids are nearer than ``Toler``. ``Toler`` defaults to 1 and is limited to the maximum model + size. + * ``MAP`` - ( :ref:`moper`, ``ParR``, ``Par1``, MAP, ``Par2``, ``Par3``, ``kDim``, ``--`` , + ``kOut``, ``LIMIT`` ) Maps the results from one set of points to another. For example, you can + map pressures from a CFD analysis onto your model for a structural analysis. ``Par1`` is the + `Nout` x 3 array of points that will be mapped to. ``Par2`` is the `Nin` x M array that contains M + values of data to be interpolated at each point and corresponds to the Nin x 3 points in ``Par3``. + The resulting ``ParR`` is the Nout x M array of mapped data points. For each point in the + destination mesh, all possible triangles in the source mesh are searched to find the best triangle + containing each point. It then does a linear interpolation inside this triangle. You should + carefully specify your interpolation method and search criteria in order to provide faster and + more accurate results (see ``LIMIT``, below). ``kDim`` is the interpolation criteria. If + ``kDim`` = 2 or 0, two dimensional interpolation is applied (interpolate on a surface). If + ``kDim`` = 3, three dimensional interpolation is applied (interpolate on a volume). ``kOut`` + specified how points outside of the domain are handled. If ``kOut`` = 0, use the value(s) of the + nearest region point for points outside of the region. If ``kOut`` = 1, set results outside of the + region to zero. ``LIMIT`` specifies the number of nearby points considered for interpolation. The + default is 20, and the minimum is 5. Lower values will reduce processing time; however, some + distorted or irregular sets of points will require a higher ``LIMIT`` value to encounter three + nodes for triangulation. Output points are incorrect if they are not within the domain (area or + volume) defined by the specified input points. Also, calculations for out-of-bound points require + much more processing time than do points that are within bounds. Results mapping is available from + the command line only. + * ``INTP`` - ( :ref:`moper`, ``ParR``, ``Par1``, INTP, ``Par2`` ) Finds the elements that + contain each point in the array of n x 3 points in ``Par1``. ``Par2`` will contain the set of + element ID numbers and ``ParR`` will contain their n x 3 set of natural element coordinates + (values between -1 and 1). ``Par1`` must be in global Cartesian coordinates. + * ``SGET`` - ( :ref:`moper`, ``ParR``, ``Par1``, SGET, ``Par2``, ``Label``, ``Comp`` ) Gets + the nodal solution item corresponding to ``Label`` and ``Comp`` (see the :ref:`plnsol` command) + and interpolates it to the given element locations. ``Par1`` contains the n x 3 array of natural + element coordinates (values between -1 and 1) of the n element ID numbers in ``Par2``. ``Par1`` + and ``Par2`` are usually the output of the :ref:`moper` ,,,INTP operation. ``ParR`` contains the n + interpolated results. + + val1 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. - operation only uses a number of rows of ``Par2`` equal to the number of columns of ``Par1`` - . + val2 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. - * ``COVAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, COVAR, ``Par2`` ) + val3 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. - Covariance: The measure of association between columns of the ``Par1`` input matrix. - ``Par1`` of - size m runs (rows) by n data (columns) is first processed to produce a row vector - containing - the mean of each column, which is transposed to the output column vector ``Par2`` of n array + val4 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. - elements. The ``Par1`` and ``Par2`` operation then produces ``ParR``, a resulting n x n - matrix - of covariances (with the variances as the diagonal terms). + val5 : str + Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending + on the specified matrix operation. See the description of ``Oper`` for details. - * ``CORR`` - ( :ref:`moper`, ``ParR``, ``Par1``, CORR, ``Par2`` ) - - Correlation: The correlation coefficient between columns of the ``Par1`` input matrix. - ``Par1`` - of size m runs (rows) by n data (columns) is first processed to produce a row vector - containing - the mean of each column, which is then transposed to the output column vector ``Par2`` of n - array elements. The ``Par1`` and ``Par2`` operation then produces ``ParR``, a resulting `n` - x n - matrix of correlation coefficients (with a value of 1.0 for the diagonal terms). - - * ``SOLV`` - ( :ref:`moper`, ``ParR``, ``Par1``, SOLV, ``Par2`` ) - - Solution of simultaneous equations: Solves the set of ``n`` equations of ``n`` terms of the - form - a n1 x 1 + a n2 x 2 + :sup:`...` + a nn x n = b n where ``Par1`` contains the matrix of - a-coefficients, ``Par2`` contains the vector(s) of b-values, and ``ParR`` contains the - vector(s) - of x-results. ``Par1`` must be a square matrix. The equations must be linear, independent, - and - well conditioned. - - Non-independent or ill-conditioned equations can cause erroneous results. - - For large matrices, use the APDL Math operation :ref:`lsfactor` for efficiency (see `APDL - Math - `_ - - * ``SORT`` - ( :ref:`moper`, ``ParR``, ``Par1``, SORT, ``Par2``, ``n1``, ``n2``, - ``n3`` ) - - Matrix sort: Sorts the columns of matrix ``Par1`` according to sort vector ``Par2`` and - places - the result back into ``Par1`` . Rows of ``Par1`` are moved to the corresponding positions - indicated by the values of ``Par2`` . ``Par2`` may be a column of ``Par1`` (in which case it - - will also be reordered). Alternatively, you may specify the column of ``Par1`` to sort using - - ``n1`` (leaving ``Par2`` blank). A secondary sort can be specified by column ``n2``, and a - third sort using column ``n3`` . ``ParR`` is the vector of initial row positions (the - permutation vector). Sorting ``Par1`` according to ``ParR`` should reproduce the initial - ordering. - - * ``NNEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, NNEAR, ``Toler`` ) - - Nearest Node: Finds the nodes nearest to the given set of points in ``Par1``, where - ``Par1`` is - an `n` x 3 array of coordinate locations. ``ParR`` is a vector of the nearest selected - nodes, - or 0 if no nodes are nearer than ``Toler`` . ``Toler`` defaults to 1 and is limited to the - maximum model size. - - * ``ENEAR`` - ( :ref:`moper`, ``ParR``, ``Par1``, ENEAR, ``Toler`` ) - - Nearest Element: Finds the elements nearest to the given set of points in ``Par1``, where - ``Par1`` is an `n` x 3 array of coordinate locations. ``ParR`` is a vector of the nearest - selected elements, or 0 if no element centroids are nearer than ``Toler`` . ``Toler`` - defaults - to 1 and is limited to the maximum model size. - - * ``MAP`` - ( :ref:`moper`, ``ParR``, ``Par1``, MAP, ``Par2``, ``Par3``, ``kDim``, - ``--`` - , ``kOut``, ``LIMIT`` ) - - Maps the results from one set of points to another. For example, you can map pressures from - a - CFD analysis onto your model for a structural analysis. - - ``Par1`` is the `Nout` x 3 array of points that will be mapped to. ``Par2`` is the `Nin` x M - - array that contains M values of data to be interpolated at each point and corresponds to the - Nin - x 3 points in ``Par3`` . The resulting ``ParR`` is the Nout x M array of mapped data - points. - - For each point in the destination mesh, all possible triangles in the source mesh are - searched - to find the best triangle containing each point. It then does a linear interpolation inside - this - triangle. You should carefully specify your interpolation method and search criteria in - order - to provide faster and more accurate results (see ``LIMIT``, below). - - ``kDim`` is the interpolation criteria. If ``kDim`` = 2 or 0, two dimensional interpolation - is - applied (interpolate on a surface). If ``kDim`` = 3, three dimensional interpolation is - applied - (interpolate on a volume). - - ``kOut`` specified how points outside of the domain are handled. If ``kOut`` = 0, use the - value(s) of the nearest region point for points outside of the region. If ``kOut`` = 1, set - results outside of the region to zero. - - ``LIMIT`` specifies the number of nearby points considered for interpolation. The default is - 20, - and the minimum is 5. Lower values will reduce processing time; however, some distorted or - irregular sets of points will require a higher ``LIMIT`` value to encounter three nodes for - triangulation. - - Output points are incorrect if they are not within the domain (area or volume) defined by - the - specified input points. Also, calculations for out-of-bound points require much more - processing - time than do points that are within bounds. Results mapping is available from the command - line - only. - - * ``INTP`` - ( :ref:`moper`, ``ParR``, ``Par1``, INTP, ``Par2`` ) - - Finds the elements that contain each point in the array of n x 3 points in ``Par1`` . - ``Par2`` - will contain the set of element ID numbers and ``ParR`` will contain their n x 3 set of - natural - element coordinates (values between -1 and 1). ``Par1`` must be in global Cartesian - coordinates. - - * ``SGET`` - ( :ref:`moper`, ``ParR``, ``Par1``, SGET, ``Par2``, ``Label``, ``Comp`` ) - - Gets the nodal solution item corresponding to ``Label`` and ``Comp`` (see the :ref:`plnsol` - command) and interpolates it to the given element locations. ``Par1`` contains the n x 3 - array - of natural element coordinates (values between -1 and 1) of the n element ID numbers in - ``Par2`` - . ``Par1`` and ``Par2`` are usually the output of the :ref:`moper` ,,,INTP operation. - ``ParR`` - contains the n interpolated results. - - val1, val2, ..., val6 : str + val6 : str Additional input used in the operation. The meanings of ``Val1`` through ``Val6`` vary depending - on the specified matrix operation. See the description of ``Oper`` for details. + on the specified matrix operation. See the description of ``Oper`` for details. Notes ----- - Each starting array element number must be defined for each array parameter matrix if it does not start at the first location. For example, :ref:`moper` ,A(2,3),B(1,4),MULT,C(1,5) multiplies submatrix B (starting at element (1,4)) by submatrix C (starting at element (1,5)) and puts the result in matrix A (starting at element (2,3)). - - The diagonal corner elements for each submatrix must be defined: the upper left corner by the array starting element (on this command), the lower right corner by the current values from the :ref:`vcol` and :ref:`vlen` commands. The default values are the (1,1) element and the last element in the matrix. No operations progress across matrix planes (in the 3rd dimension). Absolute values and scale factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Array elements should not be skipped with the :ref:`vmask` and the ``NINC`` value of the :ref:`vlen` specifications. See the :ref:`voper` command for details. - - This command is valid in any processor. + Each starting array element number must be defined for each array parameter matrix if it does not + start at the first location. For example, :ref:`moper` ,A(2,3),B(1,4),MULT,C(1,5) multiplies + submatrix B (starting at element (1,4)) by submatrix C (starting at element (1,5)) and puts the + result in matrix A (starting at element (2,3)). The diagonal corner elements for each submatrix + must be defined: the upper left corner by the array starting element (on this command), the lower + right corner by the current values from the :ref:`vcol` and :ref:`vlen` commands. The default values + are the (1,1) element and the last element in the matrix. No operations progress across matrix + planes (in the 3rd dimension). Absolute values and scale factors may be applied to all parameters ( + :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Array elements should not + be skipped with the :ref:`vmask` and the ``NINC`` value of the :ref:`vlen` specifications. See the + :ref:`voper` command for details. This command is valid in any processor. """ command = ( f"*MOPER,{parr},{par1},{oper},{val1},{val2},{val3},{val4},{val5},{val6}" ) return self.run(command, **kwargs) - def mwrite(self, parr="", label="", n1="", n2="", n3="", **kwargs): - r"""Writes a matrix to a file in a formatted sequence. + def mfouri( + self, + oper: str = "", + coeff: str = "", + mode: str = "", + isym: str = "", + theta: str = "", + curve: str = "", + **kwargs, + ): + r"""Calculates the coefficients for, or evaluates, a Fourier series. - Mechanical APDL Command: `\*MWRITE `_ + Mechanical APDL Command: `\*MFOURI `_ Parameters ---------- - parr : str - The name of the array parameter. See :ref:`starset` for name restrictions. + oper : str + Type of Fourier operation: - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - If the file name fields are left blank, the default file is the current output file. + * ``FIT`` - Calculate Fourier coefficients ``COEFF`` from ``MODE``, ``ISYM``, ``THETA``, and + ``CURVE``. + * ``EVAL`` - Evaluate the Fourier curve ``CURVE`` from ``COEFF``, ``MODE``, ``ISYM`` and ``THETA`` - ext : str - Filename extension (eight-character maximum). - label : str - Can use a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (JIK). + coeff : str + Name of the array parameter vector containing the Fourier coefficients (calculated if ``Oper`` = + FIT, required as input if ``Oper`` = EVAL). See :ref:`starset` for name restrictions. - n1, n2, n3 : str - Write as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n1,`` - ``n2,`` and ``n3`` default to the corresponding dimensions of the array parameter ParR. + mode : str + Name of the array parameter vector containing the mode numbers of the desired Fourier terms. - Notes - ----- - Writes a matrix or vector to a specified file in a formatted sequence. You can also use the :ref:`vwrite` command to write data to a specified file. Both commands contain format descriptors on the line immediately following the command. The format descriptors can be in either FORTRAN or C format. + isym : str + Name of the array parameter vector containing the symmetry key for the corresponding Fourier terms. + The vector should contain keys for each term as follows: - FORTRAN format descriptors are enclosed in parentheses. They must immediately follow the :ref:`mwrite` command on a separate line of the same input file. The word FORMAT should not be included. The format must specify the number of fields to be written per line, the field width, the placement of the decimal point, etc. There should be one field descriptor for each data item written. The write operation uses the available system FORTRAN FORMAT conventions (see your system FORTRAN manual). Any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and character format (A) may be used. Integer (I) and list-directed (\*) descriptors may `not` be used. Text may be included in the format as a quoted string. `The FORTRAN descriptor must be enclosed in parentheses` and the format must not exceed 80 characters (including parentheses). + * ``0 or 1`` - Symmetric (cosine) term + * ``-1`` - Antisymmetric (sine) term. - The "C" format descriptors are used if the first character of the format descriptor line is not a left parenthesis. "C" format descriptors may be up to 80 characters long, consisting of text strings and predefined "data descriptors" between the strings where numeric or alphanumeric character data are to be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C for alphanumeric character data, and %/ for a line break. There must be one data descriptor for each specified value in the order of the specified values. The enhanced formats described in :ref:`msg` can also be used. + theta : str + Names of the array parameter vectors containing the theta vs. curve description, respectively. + Theta values should be input in degrees. If ``Oper`` = FIT, one curve value should be supplied + with each theta value. If ``Oper`` = EVAL, one curve value will be calculated for each theta + value. - The starting array element number must be defined. Looping continues in the directions indicated by the Label argument. The number of loops and loop skipping may also be controlled via :ref:`vlen` and :ref:`vmask`, which work in the ``n2`` direction (by row on the output file), and by :ref:`vcol`, which works in the ``n1`` direction (by column in the output file). The vector specifications :ref:`vabs` and :ref:`vfact` apply to this command, while :ref:`vcum` does not apply to this command. See :ref:`voper` for details. If you are in the GUI, the :ref:`mwrite` command must be contained in an externally prepared file and read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). + curve : str + Names of the array parameter vectors containing the theta vs. curve description, respectively. + Theta values should be input in degrees. If ``Oper`` = FIT, one curve value should be supplied + with each theta value. If ``Oper`` = EVAL, one curve value will be calculated for each theta + value. + Notes + ----- + Calculates the coefficients of a Fourier series for a given curve, or evaluates the Fourier curve + from the given (or previously calculated) coefficients. The lengths of the ``COEFF``, ``MODE`` , + and ``ISYM`` vectors must be the same--typically two times the number of modes desired, since two + terms (sine and cosine) are generally required for each mode. The lengths of the ``CURVE`` and + ``THETA`` vectors should be the same or the smaller of the two will be used. There should be a + sufficient number of points to adequately define the curve--at least two times the number of + coefficients. A starting array element number (1) must be defined for each array parameter vector. + The vector specifications :ref:`vlen`, :ref:`vcol`, :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` + do not apply to this command. Array elements should not be skipped with the :ref:`vmask` and the + ``NINC`` value of the :ref:`vlen` specifications. The vector being calculated ( ``COEFF`` if + ``Oper`` is FIT, or ``CURVE`` if ``Oper`` is EVAL) must exist as a dimensioned array ( :ref:`dim` ). This command is valid in any processor. """ - command = f"*MWRITE,{parr},{label},{n1},{n2},{n3}" + command = f"*MFOURI,{oper},{coeff},{mode},{isym},{theta},{curve}" return self.run(command, **kwargs) - def sread(self, strarray="", nchar="", nskip="", nread="", **kwargs): + def sread( + self, + strarray: str = "", + fname: str = "", + ext: str = "", + nchar: str = "", + nskip: str = "", + nread: str = "", + **kwargs, + ): r"""Reads a file into a string array parameter. Mechanical APDL Command: `\*SREAD `_ @@ -396,9 +379,13 @@ def sread(self, strarray="", nchar="", nskip="", nread="", **kwargs): \*DIM,StrArray,STRING,nChar,nRead fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. + ext : str Filename extension (eight-character maximum). + nchar : str Number of characters per line to read (default is length of the longest line in the file). @@ -410,13 +397,22 @@ def sread(self, strarray="", nchar="", nskip="", nread="", **kwargs): Notes ----- - The :ref:`sread` command reads from a file into a string array parameter. The file must be an ASCII text file. + The :ref:`sread` command reads from a file into a string array parameter. The file must be an ASCII + text file. """ - command = f"*SREAD,{strarray},{nchar},{nskip},{nread}" + command = f"*SREAD,{strarray},{fname},{ext},{nchar},{nskip},{nread}" return self.run(command, **kwargs) def toper( - self, parr="", par1="", oper="", par2="", fact1="", fact2="", con1="", **kwargs + self, + parr: str = "", + par1: str = "", + oper: str = "", + par2: str = "", + fact1: str = "", + fact2: str = "", + con1: str = "", + **kwargs, ): r"""Operates on table parameters. @@ -426,7 +422,7 @@ def toper( ---------- parr : str Name of the resulting table parameter. The command will create a table array parameter with this - name. Any existing parameter with this name will be overwritten. + name. Any existing parameter with this name will be overwritten. par1 : str Name of the first table parameter. @@ -449,634 +445,650 @@ def toper( Notes ----- - :ref:`toper` operates on table parameters according to: ParR(i,j,k) = FACT1\*Par1(i,j,k) + FACT2 \*Par2(i,j,k) +CON1 - - Par1 and Par2 must have the same dimensions and the same variable names corresponding to those dimensions. Par1 and Par2 must also have identical index values for rows, columns, etc. - - If you want a local coordinate system for the resulting array, you must dimension it as such using the :ref:`dim` command before issuing :ref:`toper` . - - This command is valid in any processor. + :ref:`toper` operates on table parameters according to: ParR(i,j,k) = FACT1\*Par1(i,j,k) + FACT2 + \*Par2(i,j,k) +CON1 Par1 and Par2 must have the same dimensions and the same variable names + corresponding to those dimensions. Par1 and Par2 must also have identical index values for rows, + columns, etc. If you want a local coordinate system for the resulting array, you must dimension it + as such using the :ref:`dim` command before issuing :ref:`toper`. This command is valid in any + processor. """ command = f"*TOPER,{parr},{par1},{oper},{par2},{fact1},{fact2},{con1}" return self.run(command, **kwargs) - def vabs(self, kabsr="", kabs1="", kabs2="", kabs3="", **kwargs): - r"""Applies the absolute value function to array parameters. - - Mechanical APDL Command: `\*VABS `_ - - Parameters - ---------- - kabsr : str - Absolute value of results parameter: - - * ``0`` - Do not take absolute value of results parameter (ParR). - - * ``1`` - Take absolute value. - - kabs1 : str - Absolute value of first parameter: - - * ``0`` - Do not take absolute value of first parameter (Par1 or ParI). - - * ``1`` - Take absolute value. - - kabs2 : str - Absolute value of second parameter: - - * ``0`` - Do not take absolute value of second parameter (Par2 or ParJ). - - * ``1`` - Take absolute value. - - kabs3 : str - Absolute value of third parameter: - - * ``0`` - Do not take absolute value of third parameter (Par3 or ParK). - - * ``1`` - Take absolute value. - - Notes - ----- - Applies an absolute value to parameters used in certain \*V ``XX`` and \*M ``XX`` operations. Typical absolute value applications are of the form: ParR = \|f(\|Par1\|)\| - or - ParR = \|(\|Par1\| o \|Par2\|)\| - - The absolute values are applied to each input parameter value before the operation and to the result value after the operation. Absolute values are applied before the scale factors so that negative scale factors may be used. The absolute value settings are `reset` to the default (no absolute value) after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. - - This command is valid in any processor. - """ - command = f"*VABS,{kabsr},{kabs1},{kabs2},{kabs3}" - return self.run(command, **kwargs) - - def vcol(self, ncol1="", ncol2="", **kwargs): - r"""Specifies the number of columns in matrix operations. + def starvplot( + self, + parx: str = "", + pary: str = "", + y2: str = "", + y3: str = "", + y4: str = "", + y5: str = "", + y6: str = "", + y7: str = "", + y8: str = "", + **kwargs, + ): + r"""Graphs columns (vectors) of array parameters. - Mechanical APDL Command: `\*VCOL `_ + Mechanical APDL Command: `\*VPLOT `_ Parameters ---------- - ncol1 : str - Number of columns to be used for Par1 with \*M ``XX`` operations. Defaults to whatever is needed - to fill the result array. - - ncol2 : str - Number of columns to be used for Par2 with \*M ``XX`` operations. Defaults to whatever is needed - to fill the result array. - - Notes - ----- - Specifies the number of columns to be used in array parameter matrix operations. The size of the submatrix used is determined from the upper left starting array element (defined on the operation command) to the lower right array element (defined by the number of columns on this command and the number of rows on the :ref:`vlen` command). + parx : str + Name of the array parameter whose column vector values will be the abscissa of the graph. If + blank, row subscript numbers are used instead. ``ParX`` is not sorted by the program. - The default ``NCOL`` is calculated from the maximum number of columns of the result array (the :ref:`dim` column dimension) minus the starting location + 1. For example, :ref:`dim` ,R,,1,10 and a starting location of R(1,7) gives a default of 4 columns ( starting with R(1,7), R(1,8), R(1,9), and R(1,10)). Repeat operations automatically terminate at the last column of the result array. Existing values in the rows and columns of the results matrix remain unchanged where not overwritten by the requested input or operation values. + pary : str + Name of the array parameter whose column vector values will be graphed against the ``ParX`` + values. - The column control settings are `reset` to the defaults after each \*M ``XX`` operation. Use :ref:`vstat` to list settings. + y2 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - This command is valid in any processor. - """ - command = f"*VCOL,{ncol1},{ncol2}" - return self.run(command, **kwargs) + y3 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - def vcum(self, key="", **kwargs): - r"""Allows array parameter results to add to existing results. + y4 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - Mechanical APDL Command: `\*VCUM `_ + y5 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - Parameters - ---------- - key : str - Accumulation key: + y6 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - * ``0`` - Overwrite results. + y7 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. - * ``1`` - Add results to the current value of the results parameter. + y8 : str + Additional column subscript of the ``ParY`` array parameter whose values are to be graphed + against the ``ParX`` values. Notes ----- - Allows results from certain \*V ``XX`` and \*M ``XX`` operations to overwrite or add to existing results. The cumulative operation is of the form: ParR = ParR + ParR(Previous) - - The cumulative setting is `reset` to the default (overwrite) after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. - - This command is valid in any processor. + The column to be graphed and the starting row for each array parameter must be specified as + subscripts. Additional columns of the ``ParY`` array parameter may be graphed by specifying column + numbers for ``Y2``, ``Y3`` ,..., ``Y8``. For example, :ref:`starvplot` ,TIME (4,6), DISP (8,1),2,3 + specifies that the 1st, 2nd, and 3rd columns of array parameter DISP (all starting at row 8) are to + be graphed against the 6th column of array parameter TIME (starting at row 4). The columns are + graphed from the starting row to their maximum extent. See the :ref:`vlen` and :ref:`vmask` commands + to limit or skip data to be graphed. The array parameters specified on the :ref:`starvplot` command + must be of the same type (type ARRAY or TABLE; ( :ref:`dim` ). Arrays of type TABLE are graphed as + continuous curves. Arrays of type ARRAY is displayed in bar chart fashion. The normal curve + labeling scheme for :ref:`starvplot` is to label curve 1 "COL 1", curve 2 "COL 2" and so on. You can + use the :ref:`gcolumn` command to apply user-specified labels (8 characters maximum) to your curves. + See `Modifying Curve Labels + `_ + in the `Ansys Parametric Design Language Guide `_ for more information on using :ref:`gcolumn`. Caret 243? When a graph plot reaches + minimum or maximum y-axis limits, the program indicates the condition by clipping the graph. The + clip appears as a horizontal magenta line. Mechanical APDL calculates y-axis limits automatically; however, + you can modify the (YMIN and YMAX) limits via the :ref:`yrange` command. This command is valid in + any processor. """ - command = f"*VCUM,{key}" + command = f"*VPLOT,{parx},{pary},{y2},{y3},{y4},{y5},{y6},{y7},{y8}" return self.run(command, **kwargs) - def vedit(self, par="", **kwargs): - r"""Allows numerical array parameters to be graphically edited. + def vmask(self, par: str = "", **kwargs): + r"""Specifies an array parameter as a masking vector. - Mechanical APDL Command: `\*VEDIT `_ + Mechanical APDL Command: `\*VMASK `_ Parameters ---------- par : str - Name of the array parameter to be edited. + Name of the mask parameter. The starting subscript must also be specified. Notes ----- - Invokes a graphical editing system that displays array parameter values in matrix form, and allows the use of the mouse to edit individual values. The starting array subscripts must be defined, such as :ref:`vedit` ,A(4,6,1), to indicate the section of the array to be edited. The array section starts at the specified array element and continues to the maximum extent of the array parameter. Row and column index values may be set or changed in any plane, and those values will be applied to all planes. The menu system must be on ( :ref:`menu` ) when this command is issued. Graphical editing is not available for character array parameters. The :ref:`vedit` command can not be used in a macro or other secondary input file. - - This command is not applicable to 4- or 5-D arrays. - - This command is valid in any processor. + Specifies the name of the parameter whose values are to be checked for each resulting row operation. + The mask vector usually contains only 0 (for false) and 1 (for true) values. For each row operation + the corresponding mask vector value is checked. A true value allows the operation to be done. A + false value skips the operation (and retains the previous results). A mask vector can be created + from direct input, such as M(1) = 1,0,0,1,1,0,1; or from the DATA function of the :ref:`vfill` + command. The NOT function of the :ref:`vfun` command can be used to reverse the logical sense of the + mask vector. The logical compare operations (LT, LE, EQ, NE, GE, and GT) of the :ref:`voper` command + also produce a mask vector by operating on two other vectors. Any numeric vector can be used as a + mask vector since the actual interpretation assumes values less than 0.0 are 0.0 (false) and values + greater than 0.0 are 1.0 (true). If the mask vector is not specified (or has fewer values than the + result vector), true (1.0) values are assumed for the unspecified values. Another skip control may + be input with ``NINC`` on the :ref:`vlen` command. If both are present, operations occur only when + both are true. The mask setting is `reset` to the default (no mask) after each \*V ``XX`` or \*M + ``XX`` operation. Use :ref:`vstat` to list settings. This command is valid in any processor. """ - command = f"*VEDIT,{par}" + command = f"*VMASK,{par}" return self.run(command, **kwargs) - def vfact(self, factr="", fact1="", fact2="", fact3="", **kwargs): - r"""Applies a scale factor to array parameters. + def vcol(self, ncol1: str = "", ncol2: str = "", **kwargs): + r"""Specifies the number of columns in matrix operations. - Mechanical APDL Command: `\*VFACT `_ + Mechanical APDL Command: `\*VCOL `_ Parameters ---------- - factr : str - Scale factor applied to results (ParR) parameter. Defaults to 1.0. - - fact1 : str - Scale factor applied to first parameter (Par1 or ParI). Defaults to 1.0. - - fact2 : str - Scale factor applied to second parameter (Par2 or ParJ). Defaults to 1.0. + ncol1 : str + Number of columns to be used for Par1 with \*M ``XX`` operations. Defaults to whatever is needed + to fill the result array. - fact3 : str - Scale factor applied to third parameter (Par3 or ParK). Defaults to 1.0. + ncol2 : str + Number of columns to be used for Par2 with \*M ``XX`` operations. Defaults to whatever is needed + to fill the result array. Notes ----- - Applies a scale factor to parameters used in certain \*V ``XX`` and \*M ``XX`` operations. Typical scale factor applications are of the form: ParR = ``FACTR`` \*f( ``FACT1`` \*Par1) - or - ParR = ``FACTR`` \*(( ``FACT1`` \*Par1) o ( ``FACT2`` \*Par2)) - - The factors are applied to each input parameter value before the operation and to the result value after the operation. The scale factor settings are `reset` to the default (1.0) after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. - - This command is valid in any processor. + Specifies the number of columns to be used in array parameter matrix operations. The size of the + submatrix used is determined from the upper left starting array element (defined on the operation + command) to the lower right array element (defined by the number of columns on this command and the + number of rows on the :ref:`vlen` command). The default ``NCOL`` is calculated from the maximum + number of columns of the result array (the :ref:`dim` column dimension) minus the starting location + + 1. For example, :ref:`dim` ,R,,1,10 and a starting location of R(1,7) gives a default of 4 columns + ( starting with R(1,7), R(1,8), R(1,9), and R(1,10)). Repeat operations automatically terminate at + the last column of the result array. Existing values in the rows and columns of the results matrix + remain unchanged where not overwritten by the requested input or operation values. The column + control settings are `reset` to the defaults after each \*M ``XX`` operation. Use :ref:`vstat` to + list settings. This command is valid in any processor. """ - command = f"*VFACT,{factr},{fact1},{fact2},{fact3}" + command = f"*VCOL,{ncol1},{ncol2}" return self.run(command, **kwargs) - def vfun(self, parr="", func="", par1="", con1="", con2="", con3="", **kwargs): - r"""Performs a function on a single array parameter. + def vscfun(self, parr: str = "", func: str = "", par1: str = "", **kwargs): + r"""Determines properties of an array parameter. - Mechanical APDL Command: `\*VFUN `_ + Mechanical APDL Command: `\*VSCFUN `_ Parameters ---------- parr : str - The name of the resulting numeric array parameter vector. See :ref:`starset` for name - restrictions. + The name of the resulting scalar parameter. See :ref:`starset` for name restrictions. func : str - Function to be performed: - - * ``ACOS`` - Arccosine: ACOS( ``Par1`` ). - - * ``ASIN`` - Arcsine: ASIN( ``Par1`` ). - - * ``ASORT`` - Par1 is sorted in ascending order. :ref:`vcol`, :ref:`vmask`, :ref:`vcum`, - and - :ref:`vlen` ,,NINC do not apply. :ref:`vlen` ,NROW does apply. - - * ``ATAN`` - Arctangent: ATAN( ``Par1`` ). - - * ``COMP`` - Compress: Selectively compresses data set. "True" ( :ref:`vmask` ) values of - ``Par1`` (or row positions to be considered according to the ``NINC`` value on the :ref:`vlen` - - command) are written in compressed form to ``ParR``, starting at the specified position. - - * ``COPY`` - Copy: ``Par1`` copied to ``ParR`` . - - * ``COS`` - Cosine: COS( ``Par1`` ). - - * ``COSH`` - Hyperbolic cosine: COSH( ``Par1`` ). - - * ``DIRCOS`` - Direction cosines of the principal stresses ( ``n`` X9). ``Par1`` contains - the - ``n`` X6 component stresses for the ``n`` locations of the calculations. - - * ``DSORT`` - ``Par1`` is sorted in descending order. :ref:`vcol`, :ref:`vmask`, - :ref:`vcum` , - and :ref:`vlen` ,,NINC do not apply. :ref:`vlen` ,NROW does apply. - - * ``EULER`` - Euler angles of the principal stresses ( ``n`` X3). ``Par1`` contains the - ``n`` X6 - component stresses for the ``n`` locations of the calculations. - - * ``EXP`` - Exponential: EXP( ``Par1`` ). - - * ``EXPA`` - Expand: Reverse of the COMP function. All elements of ``Par1`` (starting at the - - position specified) are written in expanded form to corresponding "true" ( :ref:`vmask` ) - positions (or row positions to be considered according to the ``NINC`` value on the - :ref:`vlen` - command) of ``ParR`` . - - * ``LOG`` - Natural logarithm: LOG( ``Par1`` ). - - * ``LOG10`` - Common logarithm: LOG10( ``Par1`` ). - - * ``NINT`` - Nearest integer: 2.783 becomes 3.0, -1.75 becomes -2.0. - - * ``NOT`` - Logical complement: values :math:`` 0.0 (false) become 1.0 (true). Values > - 0.0 - (true) become#130.0 (false). - - * ``PRIN`` - Principal stresses ( ``n`` X5). ``Par1`` contains the ``n`` X6 component - stresses - for the ``n`` locations of the calculations. - - * ``PWR`` - Power function: ``Par1`` \*\* ``CON1`` . Exponentiation of any negative number in - the - vector ``Par1`` to a non-integer power is performed by exponentiating the positive number and - prepending the minus sign. For example, -4\*\*2.3 is -(4\*\*2.3). - - * ``SIN`` - Sine: SIN( ``Par1`` ). - - * ``SINH`` - Hyperbolic sine: SINH( ``Par1`` ). - - * ``SQRT`` - Square root: SQRT( ``Par1`` ). - - * ``TAN`` - Tangent: TAN( ``Par1`` ). - - * ``TANH`` - Hyperbolic tangent: TANH( ``Par1`` ). - - * ``TANG`` - Tangent to a path at a point: the slope at a point is determined by linear - interpolation half way between the previous and next points. Points are assumed to be in the - global Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 - consecutive columns of data, with the columns containing the x, y, and z coordinate locations, - - respectively, of the points). Only the starting row index and the column index for the x - coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed - to - begin in the corresponding next columns, such as A(1,2) and A(1,3). The tangent result, - ``ParR`` , - must also have 3 consecutive columns of data and will contain the tangent direction vector - (normalized to 1.0); such as 1,0,0 for an x-direction vector. - - * ``NORM`` - Normal to a path and an input vector at a point: determined from the cross- - product - of the calculated tangent vector (see TANG) and the input direction vector (with the i, j, and - k - components input as ``CON1``, ``CON2``, and ``CON3`` ). Points are assumed to be in the - global - Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 consecutive - - columns of data, with the columns containing the x, y, and z coordinate locations, - respectively, - of the points). Only the starting row index and the column index for the x coordinates are - specified, such as A(1,1). The y and z coordinates of the vector are assumed to begin in the - corresponding next columns, such as A(1,2) and A(1,3). The normal result, ``ParR``, must also - - have 3 consecutive columns of data and will contain the normal direction vector (normalized to - - 1.0); such as 1,0,0 for an x-direction vector. - - * ``LOCAL`` - Transforms global Cartesian coordinates of a point to the coordinates of a - specified system: points to be transformed are specified in array ``Par1`` (having 3 - consecutive - columns of data, with the columns containing the x, y, and z global Cartesian coordinate - locations, respectively, of the points). Only the starting row index and the column index for - the - x coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed - to - begin in the corresponding next columns, such as A(1,2) and A(1,3). Results are transformed to - - coordinate system ``CON1`` (which may be any valid coordinate system number, such as - 1,2,11,12, - etc.). The transformed result, ``ParR``, must also have 3 consecutive columns of data and - will - contain the corresponding transformed coordinate locations. + Functions: - * ``GLOBAL`` - Transforms specified coordinates of a point to global Cartesian coordinates: - points to be transformed are specified in array ``Par1`` (having 3 consecutive columns of - data, - with the columns containing the local coordinate locations (x, y, z or r, θ, z or etc.) - of - the points). Only the starting row index and the column index for the x coordinates are - specified, - such as A(1,1). The y and z coordinates (or θ and z, or etc.) of the vector are - assumed to - begin in the corresponding next columns, such as A(1,2) and A(1,3). Local coordinate - locations - are assumed to be in coordinate system ``CON1`` (which may be any valid coordinate system - number, - such as 1,2,11,12, etc.). The transformed result, ``ParR``, must also have 3 consecutive - columns - of data, with the columns containing the global Cartesian x, y, and z coordinate locations, - respectively. + * ``MAX`` - Maximum: the maximum ``Par1`` array element value. + * ``MIN`` - Minimum: the minimum ``Par1`` array element value. + * ``LMAX`` - Index location of the maximum ``Par1`` array element value. Array ``Par1`` is searched + starting from its specified index. + * ``LMIN`` - Index location of the minimum ``Par1`` array element value. Array ``Par1`` is searched + starting from its specified index. + * ``FIRST`` - Index location of the first nonzero value in array ``Par1``. Array ``Par1`` is + searched starting from its specified index. + * ``LAST`` - Index location of the last nonzero value in array ``Par1``. Array ``Par1`` is searched + starting from its specified index. + * ``SUM`` - Sum: ``Par1`` (the summation of the ``Par1`` array element values). + * ``MEDI`` - Median: value of ``Par1`` at which there are an equal number of values above and below. + * ``MEAN`` - Mean: (σ Par1)/NUM, where NUM is the number of summed values. + * ``VARI`` - Variance: (σ (( ``Par1`` -MEAN)\*\*2))/NUM. + * ``STDV`` - Standard deviation: square root of VARI. + * ``RMS`` - Root-mean-square: square root of (σ ( ``Par1`` \*\*2))/NUM. + * ``NUM`` - Number: the number of summed values (masked values are not counted). par1 : str Array parameter vector in the operation. - con1, con2, con3 : str - Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). - Notes ----- - Operates on one input array parameter vector and produces one output array parameter vector according to: ``ParR`` = f( ``Par1`` ) - - where the functions (f) are described below. Functions are based on the standard FORTRAN definitions where possible. Out-of-range function results (or results with exponents whose magnitudes are approximately greater than 32 or less than -32) produce a zero value. Input and output for angular functions may be radians (default) or degrees ( :ref:`afun` ). ``ParR`` may be the same as ``Par1`` . Starting array element numbers must be defined for each array parameter vector if it does not start at the first location. For example, :ref:`vfun` ,A,SQRT,B(5) takes the square root of the fifth element of B and stores the result in the first element of A. Operations continue on successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. Absolute values and scale factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Skipping array elements via :ref:`vmask` or :ref:`vlen` for the TANG and NORM functions skips only the writing of the results (skipped array element data are used in all calculations). See the :ref:`voper` command for details. - - This command is valid in any processor. + Operates on one input array parameter vector and produces one output scalar parameter according to: + ``ParR`` = f( ``Par1`` ) where the functions (f) are described below. The starting array element + number must be defined for the array parameter vector. For example, :ref:`vscfun` ,MU,MEAN,A(1) + finds the mean of the A vector values, starting from the first value and stores the result as + parameter MU. Operations use successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the + default being all successive array elements. Absolute values and scale factors may be applied to all + parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the + :ref:`voper` command for details. This command is valid in any processor. """ - command = f"*VFUN,{parr},{func},{par1},{con1},{con2},{con3}" + command = f"*VSCFUN,{parr},{func},{par1}" return self.run(command, **kwargs) - def vitrp(self, parr="", part="", pari="", parj="", park="", **kwargs): - r"""Forms an array parameter by interpolation of a table. - - Mechanical APDL Command: `\*VITRP `_ - - Parameters - ---------- - parr : str - The name of the resulting array parameter. See :ref:`starset` for name restrictions. - - part : str - The name of the TABLE array parameter. The parameter must exist as a dimensioned array of type - TABLE ( :ref:`dim` ). - - pari : str - Array parameter vector of I (row) index values for interpolation in ``ParT`` . - - parj : str - Array parameter vector of J (column) index values for interpolation in ``ParT`` (which must be - at least 2D). + def vstat(self, **kwargs): + r"""Lists the current specifications for the array parameters. - park : str - Array parameter vector of K (depth) index values for interpolation in ``ParT`` (which must be - 3D). + Mechanical APDL Command: `\*VSTAT `_ Notes ----- - Forms an array parameter (of type ARRAY) by interpolating values of an array parameter (of type TABLE) at specified table index locations according to: ``ParR`` = f( ``ParT``, ``Parl``, ``ParJ``, ``ParK`` ) - - where ``ParT`` is the type TABLE array parameter, and ``ParI``, ``ParJ``, ``ParK`` are the type ARRAY array parameter vectors of index values for interpolation in ``ParT`` . See the :ref:`dim` command for TABLE and ARRAY declaration types. Linear interpolation is used. The starting array element number for the TABLE array ( ``ParT`` ) is not used (but a value must be input). Starting array element numbers must be defined for each array parameter vector if it does not start at the first location. For example, :ref:`vitrp` ,R(5),TAB(1,1),X(2),Y(4) uses the second element of X and the fourth element of Y as index values (row and column) for a 2D interpolation in TAB and stores the result in the fifth element of R. Operations continue on successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. Absolute values and scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. - - This command is valid in any processor. + Lists the current specifications for the :ref:`vabs`, :ref:`vcol`, :ref:`vcum`, :ref:`vfact` , + :ref:`vlen`, and :ref:`vmask` commands. This command is valid in any processor. """ - command = f"*VITRP,{parr},{part},{pari},{parj},{park}" + command = f"*VSTAT" return self.run(command, **kwargs) - def vlen(self, nrow="", ninc="", **kwargs): - r"""Specifies the number of rows to be used in array parameter operations. + def voper( + self, + parr: str = "", + par1: str = "", + oper: str = "", + par2: str = "", + con1: str = "", + con2: str = "", + **kwargs, + ): + r"""Operates on two array parameters. - Mechanical APDL Command: `\*VLEN `_ + Mechanical APDL Command: `\*VOPER `_ Parameters ---------- - nrow : str - Number of rows to be used with the \*V ``XX`` or \*M ``XX`` operations. Defaults to the number - of rows needed to fill the result array. - - ninc : str - Perform the operation on every ``NINC`` row (defaults to 1). - - Notes - ----- - Specifies the number of rows to be used in array parameter operations. The size of the submatrix used is determined from the upper left starting array element (defined on the operation command) to the lower right array element (defined by the number of rows on this command and the number of columns on the :ref:`vcol` command). ``NINC`` allows skipping row operations for some operation commands. Skipped rows are included in the row count. The starting row number must be defined on the operation command for each parameter read and for the result written. + parr : str + The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. - The default ``NROW`` is calculated from the maximum number of rows of the result array (the :ref:`dim` row dimension) minus the starting location + 1. For example, :ref:`dim` ,R,,10 and a starting location of R(7) gives a default of 4 loops (filling R(7), R(8), R(9), and R(10)). Repeat operations automatically terminate at the last row of the result array. Existing values in the rows and columns of the results matrix remain unchanged where not overwritten by the requested input or operation values. + par1 : str + First array parameter vector in the operation. May also be a scalar parameter or a literal + constant. - The stride ( ``NINC`` ) allows operations to be performed at regular intervals. It has no effect on the total number of row operations. Skipped operations retain the previous result. For example, :ref:`dim` ,R,,6, with a starting location of R(1), ``NROW`` = 10, and ``NINC`` = 2 calculates values for locations R(1), R(3), and R(5) and retains values for locations R(2), R(4), and R(6). A more general skip control may be done by masking ( :ref:`vmask` ). The row control settings are `reset` to the defaults after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. + oper : str + Operations: - This command is valid in any processor. - """ - command = f"*VLEN,{nrow},{ninc}" - return self.run(command, **kwargs) + * ``ADD`` - Addition: ``Par1`` + ``Par2``. + * ``SUB`` - Subtraction: ``Par1`` - ``Par2``. + * ``MULT`` - Multiplication: ``Par1`` * ``Par2``. + * ``DIV`` - Division: ``Par1`` / ``Par2`` (a divide by zero results in a value of zero). + * ``MIN`` - Minimum: minimum of ``Par1`` and ``Par2``. + * ``MAX`` - Maximum: maximum of ``Par1`` and ``Par2``. + * ``LT`` - Less than comparison: ``Par1`` < ``Par2`` gives 1.0 if true, 0.0 if false. + * ``LE`` - Less than or equal comparison: ``Par1`` :math:`` ``Par2`` gives 1.0 if true, 0.0 if + false. + * ``EQ`` - Equal comparison: ``Par1`` = ``Par2`` gives 1.0 if true, 0.0 if false. + * ``NE`` - Not equal comparison: ``Par1`` ≠ ``Par2`` gives 1.0 if true, 0.0 if false. + * ``GE`` - Greater than or equal comparison: ``Par1`` :math:`` Par2 gives 1.0 if true, 0.0 if + false. + * ``GT`` - Greater than comparison: ``Par1`` > ``Par2`` gives 1.0 if true, 0.0 if false. + * ``DER1`` - First derivative: d( ``Par1`` )/d( ``Par2`` ). The derivative at a point is determined + over points half way between the previous and next points (by linear interpolation). ``Par1`` must + be a function (a unique ``Par1`` value for each ``Par2`` value) and ``Par2`` must be in ascending + order. + * ``DER2`` - Second derivative: d :sup:`2` ( ``Par1`` )/d( ``Par2`` ) :sup:`2`. See also DER1. + * ``INT1`` - Single integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration constant. + The integral at a point is determined by using the single integration procedure described in the + `Theory Reference `_. + * ``INT2`` - Double integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration constant + of the first integral and ``CON2`` is the integration constant of the second integral. If ``Par1`` + contains acceleration data, ``CON1`` is the initial velocity and ``CON2`` is the initial + displacement. See also INT1. + * ``DOT`` - Dot product: ``Par1``. ``Par2``. ``Par1`` and ``Par2`` must each have three consecutive + columns of data, with the columns containing the i, j, and k vector components, respectively. Only + the starting row index and the column index for the i components are specified for ``Par1`` and + ``Par2``, such as A(1,1). The j and k components of the vector are assumed to begin in the + corresponding next columns, such as A(1,2) and A(1,3). + * ``CROSS`` - Cross product: ``Par1`` x ``Par2``. ``Par1``, ``Par2``, and ``ParR`` must each have + 3 components, respectively. Only the starting row index and the column index for the i components + are specified for ``Par1``, ``Par2``, and ``ParR``, such as A(1,1). The j and k components of + the vector are assumed to begin in the corresponding next columns, such as A(1,2) and A(1,3). + * ``GATH`` - Gather: For a vector of position numbers, ``Par2``, copy the value of ``Par1`` at each + position number to ``ParR``. Example: for ``Par1`` = 10,20,30,40 and ``Par2`` = 2,4,1; ``ParR`` = + 20,40,10. + * ``SCAT`` - Scatter: Opposite of GATH operation. For a vector of position numbers, ``Par2``, copy + the value of ``Par1`` to that position number in ``ParR``. Example: for ``Par1`` = 10,20,30,40,50 + and ``Par2`` = 2,1,0,5,3; ``ParR`` = 20,10,50,0,40. + * ``ATN2`` - Arctangent: arctangent of ``Par1`` / ``Par2`` with the sign of each component + considered. + * ``LOCAL`` - Transform the data in ``Par1`` from the global Cartesian coordinate system to the + local coordinate system given in ``CON1``. ``Par1`` must be an `N x 3` (that is, vector) or an `N + x 6` (that is, stress or strain tensor) array. If the local coordinate system is a cylindrical, + spherical, or toroidal system, then you must provide the global Cartesian coordinates in ``Par2`` + as an `N x 3` array. Set ``CON2`` = 1 if the data is strain data. + * ``GLOBAL`` - Transform the data in ``Par1`` from the local coordinate system given in ``CON1`` to + the global Cartesian coordinate system. ``Par1`` must be an `N x 3` (that is, vector) or an `N x + 6` (that is, stress or strain tensor) array. If the local coordinate system is a cylindrical, + spherical, or toroidal system, then you must provide the global Cartesian coordinates in ``Par2`` + as an `N x 3` array. Set ``CON2`` = 1 if the data is strain data. - def vmask(self, par="", **kwargs): - r"""Specifies an array parameter as a masking vector. + par2 : str + Second array parameter vector in the operation. May also be a scalar parameter or a literal + constant. - Mechanical APDL Command: `\*VMASK `_ + con1 : str + First constant (used only with the INT1 and INT2 operations). - Parameters - ---------- - par : str - Name of the mask parameter. The starting subscript must also be specified. + con2 : str + Second constant (used only with the INT2 operation). Notes ----- - Specifies the name of the parameter whose values are to be checked for each resulting row operation. The mask vector usually contains only 0 (for false) and 1 (for true) values. For each row operation the corresponding mask vector value is checked. A true value allows the operation to be done. A false value skips the operation (and retains the previous results). A mask vector can be created from direct input, such as M(1) = 1,0,0,1,1,0,1; or from the DATA function of the :ref:`vfill` command. The NOT function of the :ref:`vfun` command can be used to reverse the logical sense of the mask vector. The logical compare operations (LT, LE, EQ, NE, GE, and GT) of the :ref:`voper` command also produce a mask vector by operating on two other vectors. Any numeric vector can be used as a mask vector since the actual interpretation assumes values less than 0.0 are 0.0 (false) and values greater than 0.0 are 1.0 (true). If the mask vector is not specified (or has fewer values than the result vector), true (1.0) values are assumed for the unspecified values. Another skip control may be input with ``NINC`` on the :ref:`vlen` command. If both are present, operations occur only when both are true. The mask setting is `reset` to the default (no mask) after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. - - This command is valid in any processor. + Operates on two input array parameter vectors and produces one output array parameter vector + according to: ``ParR`` = ``Par1`` o ``Par2`` where the operations (o) are described below. + ``ParR`` can be the same as ``Par1`` or ``Par2``. Absolute values and scale factors can be applied + to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results can be cumulative ( :ref:`vcum` ). + Starting array element numbers must be defined for each array parameter vector if it does not start + at the first location, such as :ref:`voper` ,A,B(5),ADD,C(3) which adds the third element of C to + the fifth element of B and stores the result in the first element of A. Operations continue on + successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive + elements. Skipping array elements via :ref:`vmask` or :ref:`vlen` for the DER and INT functions + skips only the writing of the results (skipped array element data are used in all calculations). + Parameter functions and operations are available to operate on a scalar parameter or a single + element of an array parameter, such as SQRT(B) or SQRT(A(4)). (See :ref:`starset` for more + information.) Operations on a sequence of array elements can be performed by repeating the desired + function or operation in a do-loop ( :ref:`do` ). The vector operations within Mechanical APDLm ( \*V ``XX`` + commands) are internally programmed do-loops that conveniently perform the indicated operation over + a sequence of array elements. If the array is multidimensional, only the first subscript is + incremented in the do-loop; that is, the operation repeats in column vector fashion down the array. + For example, for A(1,5), A(2,5), A(3,5), etc. The starting location of the row index must be defined + for each parameter read and for the result written. The default number of loops is from the + starting result location to the last result location and can be altered via :ref:`vlen`. A logical + mask vector can be defined to control at which locations the operations are to be skipped ( + :ref:`vmask` ). The default is to skip no locations. Repeat operations automatically terminate at + the last array element of the result array column if the number of loops is undefined or if it + exceeds the last result array element. Zeroes are used in operations for values read beyond the + last array element of an input array column. Existing values in the rows and columns of the results + matrix remain unchanged where not changed by the requested operation values. The result array + column may be the same as the input array column, as results in progress are stored in a temporary + array until being moved to the results array at the end of the operation. Results may be overwritten + or accumulated with the existing results ( :ref:`vcum` ). The default is to overwrite results. The + absolute value can be used for each parameter read or written ( :ref:`vabs` ). A scale factor + (defaulting to 1.0) is also applied to each parameter read and written ( :ref:`vfact` ). This + command is valid in any processor. """ - command = f"*VMASK,{par}" + command = f"*VOPER,{parr},{par1},{oper},{par2},{con1},{con2}" return self.run(command, **kwargs) - def voper(self, parr="", par1="", oper="", par2="", con1="", con2="", **kwargs): - r"""Operates on two array parameters. + def vwrite( + self, + par1: str = "", + par2: str = "", + par3: str = "", + par4: str = "", + par5: str = "", + par6: str = "", + par7: str = "", + par8: str = "", + par9: str = "", + par10: str = "", + par11: str = "", + par12: str = "", + par13: str = "", + par14: str = "", + par15: str = "", + par16: str = "", + par17: str = "", + par18: str = "", + par19: str = "", + **kwargs, + ): + r"""Writes data to a file in a formatted sequence. - Mechanical APDL Command: `\*VOPER `_ + Mechanical APDL Command: `\*VWRITE `_ Parameters ---------- - parr : str - The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. - par1 : str - First array parameter vector in the operation. May also be a scalar parameter or a literal - constant. + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - oper : str - Operations: + par2 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``ADD`` - Addition: ``Par1`` + ``Par2`` . + par3 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``SUB`` - Subtraction: ``Par1`` - ``Par2`` . + par4 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``MULT`` - Multiplication: ``Par1`` * ``Par2`` . + par5 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``DIV`` - Division: ``Par1`` / ``Par2`` (a divide by zero results in a value of zero). + par6 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``MIN`` - Minimum: minimum of ``Par1`` and ``Par2`` . + par7 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``MAX`` - Maximum: maximum of ``Par1`` and ``Par2`` . + par8 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``LT`` - Less than comparison: ``Par1`` < ``Par2`` gives 1.0 if true, 0.0 if false. + par9 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``LE`` - Less than or equal comparison: ``Par1`` :math:`` #13 ``Par2`` gives 1.0 if - true, - 0.0 if false. + par10 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``EQ`` - Equal comparison: ``Par1`` = ``Par2`` gives 1.0 if true, 0.0 if false. + par11 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``NE`` - Not equal comparison: ``Par1`` ≠ ``Par2`` gives 1.0 if true, 0.0 if false. + par12 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``GE`` - Greater than or equal comparison: ``Par1`` :math:`` Par2 gives 1.0 if true, 0.0 - if - false. + par13 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``GT`` - Greater than comparison: ``Par1`` > ``Par2`` gives 1.0 if true, 0.0 if false. - - * ``DER1`` - First derivative: d( ``Par1`` )/d( ``Par2`` ). The derivative at a point is - determined over points half way between the previous and next points (by linear - interpolation). - ``Par1`` must be a function (a unique ``Par1`` value for each ``Par2`` value) and ``Par2`` - must be - in ascending order. - - * ``DER2`` - Second derivative: d :sup:`2` ( ``Par1`` )/d( ``Par2`` ) :sup:`2` . See also - DER1. - - * ``INT1`` - Single integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration - constant. The integral at a point is determined by using the single integration procedure - described in the `Theory Reference `_. - - * ``INT2`` - Double integral: ``Par1`` d( ``Par2`` ), where ``CON1`` is the integration - constant of the first integral and ``CON2`` is the integration constant of the second - integral. If - ``Par1`` contains acceleration data, ``CON1`` is the initial velocity and ``CON2`` is the - initial - displacement. See also INT1. - - * ``DOT`` - Dot product: ``Par1`` . ``Par2`` . ``Par1`` and ``Par2`` must each have three - consecutive columns of data, with the columns containing the i, j, and k vector components, - respectively. Only the starting row index and the column index for the i components are - specified - for ``Par1`` and ``Par2``, such as A(1,1). The j and k components of the vector are assumed - to - begin in the corresponding next columns, such as A(1,2) and A(1,3). - - * ``CROSS`` - Cross product: ``Par1`` x ``Par2`` . ``Par1``, ``Par2``, and ``ParR`` must - each - have 3 components, respectively. Only the starting row index and the column index for the i - components are specified for ``Par1``, ``Par2``, and ``ParR``, such as A(1,1). The j and k - components of the vector are assumed to begin in the corresponding next columns, such as - A(1,2) - and A(1,3). - - * ``GATH`` - Gather: For a vector of position numbers, ``Par2``, copy the value of ``Par1`` - at - each position number to ``ParR`` . Example: for ``Par1`` = 10,20,30,40 and ``Par2`` = 2,4,1; - ``ParR`` = 20,40,10. - - * ``SCAT`` - Scatter: Opposite of GATH operation. For a vector of position numbers, ``Par2`` - , - copy the value of ``Par1`` to that position number in ``ParR`` . Example: for ``Par1`` = - 10,20,30,40,50 and ``Par2`` = 2,1,0,5,3; ``ParR`` = 20,10,50,0,40. - - * ``ATN2`` - Arctangent: arctangent of ``Par1`` / ``Par2`` with the sign of each component - considered. + par14 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``LOCAL`` - Transform the data in ``Par1`` from the global Cartesian coordinate system to - the - local coordinate system given in ``CON1`` . ``Par1`` must be an `N x 3` (that is, vector) or - an `N - x 6` (that is, stress or strain tensor) array. If the local coordinate system is a - cylindrical, - spherical, or toroidal system, then you must provide the global Cartesian coordinates in - ``Par2`` - as an `N x 3` array. Set ``CON2`` = 1 if the data is strain data. + par15 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - * ``GLOBAL`` - Transform the data in ``Par1`` from the local coordinate system given in - ``CON1`` - to the global Cartesian coordinate system. ``Par1`` must be an `N x 3` (that is, vector) or - an `N - x 6` (that is, stress or strain tensor) array. If the local coordinate system is a - cylindrical, - spherical, or toroidal system, then you must provide the global Cartesian coordinates in - ``Par2`` - as an `N x 3` array. Set ``CON2`` = 1 if the data is strain data. + par16 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - par2 : str - Second array parameter vector in the operation. May also be a scalar parameter or a literal - constant. + par17 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - con1 : str - First constant (used only with the INT1 and INT2 operations). + par18 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. - con2 : str - Second constant (used only with the INT2 operation). + par19 : str + You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` + value are ignored. If you leave them all blank, one line will be written (to write a title or a + blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be + written for that item. Notes ----- - Operates on two input array parameter vectors and produces one output array parameter vector according to: ``ParR`` = ``Par1`` o ``Par2`` - where the operations (o) are described below. ``ParR`` can be the same as ``Par1`` or ``Par2`` . - - Absolute values and scale factors can be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results can be cumulative ( :ref:`vcum` ). - - Starting array element numbers must be defined for each array parameter vector if it does not start at the first location, such as :ref:`voper` ,A,B(5),ADD,C(3) which adds the third element of C to the fifth element of B and stores the result in the first element of A. - - Operations continue on successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. - - Skipping array elements via :ref:`vmask` or :ref:`vlen` for the DER and INT functions skips only the writing of the results (skipped array element data are used in all calculations). - - Parameter functions and operations are available to operate on a scalar parameter or a single element of an array parameter, such as SQRT(B) or SQRT(A(4)). (See :ref:`starset` for more information.) + You use :ref:`vwrite` to write data to a file in a formatted sequence. Data items ( ``Par1`` , + ``Par2``, etc.) may be array parameters, scalar parameters, character parameters (scalar or array), + or constants. You must evaluate expressions and functions in the data item fields before using the + :ref:`vwrite` command, since initially they will be evaluated to a constant and remain constant + throughout the operation. Unless a file is defined with the :ref:`cfopen` command, data is written + to the standard output file. Data written to the standard output file may be diverted to a different + file by first switching the current output file with the :ref:`output` command. You can also use the + :ref:`mwrite` command to write data to a specified file. Both commands contain format descriptors on + the line immediately following the command. The format descriptors can be in either FORTRAN or C + format. You must enclose FORTRAN format descriptors in parentheses. They must immediately follow + the :ref:`vwrite` command on a separate line of the same input file. Do not include the word FORMAT. + The format must specify the number of fields to be written per line, the field width, the placement + of the decimal point, etc. You should use one field descriptor for each data item written. The write + operation uses your system's available FORTRAN FORMAT conventions (see your system FORTRAN manual). + You can use any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and + alphanumeric format (A). Alphanumeric strings are limited to a maximum of 8 characters for any field + (A8) using the FORTRAN format. Use the "C" format for string arrays larger than 8 characters. + Integer (I) and list-directed (\*) descriptors may `not` be used. You can include text in the format + as a quoted string. `The parentheses must be included in the format` and the format must not exceed + 80 characters (including parentheses). The output line length is limited to 128 characters. The "C" + format descriptors are used if the first character of the format descriptor line is not a left + parenthesis. "C" format descriptors are up to 80 characters long, consisting of text strings and + predefined "data descriptors" between the strings where numeric or alphanumeric character data will + be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C for + alphanumeric character data, and %/ for a line break. There must be one data descriptor for each + specified value (8 maximum) in the order of the specified values. The enhanced formats described in + :ref:`msg` may also be used. For array parameter items, you must define the starting array element + number. Looping continues (incrementing the vector index number of each array parameter by one) each + time you output a line, until the maximum array vector element is written. For example, + :ref:`vwrite` ,A(1) followed by (F6.0) will write one value per output line, that is, A(1), A(2), + A(3), A(4), etc. You write constants and scalar parameters with the same values for each loop. You + can also control the number of loops and loop skipping with the :ref:`vlen` and :ref:`vmask` + commands. The vector specifications :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` do not apply to + this command. If looping continues beyond the supplied data array's length, zeros will be output for + numeric array parameters and blanks for character array parameters. For multi-dimensioned array + parameters, only the first (row) subscript is incremented. See the :ref:`voper` command for details. + If you are in the GUI, the :ref:`vwrite` command must be contained in an externally prepared file + and read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). If ``Par`` is a table array + name, the subscripts refer to the index numbers of the table and not the index values of its primary + variables. See :ref:`starset` if you want to evaluate a table array at certain values of its primary + variables for writing. This command is valid in any processor. + """ + command = f"*VWRITE,{par1},{par2},{par3},{par4},{par5},{par6},{par7},{par8},{par9},{par10},{par11},{par12},{par13},{par14},{par15},{par16},{par17},{par18},{par19}" + return self.run(command, **kwargs) - Operations on a sequence of array elements can be performed by repeating the desired function or operation in a do-loop ( :ref:`do` ). The vector operations within Mechanical APDLm ( \*V ``XX`` commands) are internally programmed do-loops that conveniently perform the indicated operation over a sequence of array elements. If the array is multidimensional, only the first subscript is incremented in the do-loop; that is, the operation repeats in column vector fashion down the array. For example, for A(1,5), A(2,5), A(3,5), etc. The starting location of the row index must be defined for each parameter read and for the result written. + def vitrp( + self, + parr: str = "", + part: str = "", + pari: str = "", + parj: str = "", + park: str = "", + **kwargs, + ): + r"""Forms an array parameter by interpolation of a table. - The default number of loops is from the starting result location to the last result location and can be altered via :ref:`vlen` . + Mechanical APDL Command: `\*VITRP `_ - A logical mask vector can be defined to control at which locations the operations are to be skipped ( :ref:`vmask` ). The default is to skip no locations. + Parameters + ---------- + parr : str + The name of the resulting array parameter. See :ref:`starset` for name restrictions. - Repeat operations automatically terminate at the last array element of the result array column if the number of loops is undefined or if it exceeds the last result array element. + part : str + The name of the TABLE array parameter. The parameter must exist as a dimensioned array of type + TABLE ( :ref:`dim` ). - Zeroes are used in operations for values read beyond the last array element of an input array column. Existing values in the rows and columns of the results matrix remain unchanged where not changed by the requested operation values. + pari : str + Array parameter vector of I (row) index values for interpolation in ``ParT``. - The result array column may be the same as the input array column, as results in progress are stored in a temporary array until being moved to the results array at the end of the operation. Results may be overwritten or accumulated with the existing results ( :ref:`vcum` ). The default is to overwrite results. + parj : str + Array parameter vector of J (column) index values for interpolation in ``ParT`` (which must be + at least 2D). - The absolute value can be used for each parameter read or written ( :ref:`vabs` ). A scale factor (defaulting to 1.0) is also applied to each parameter read and written ( :ref:`vfact` ). + park : str + Array parameter vector of K (depth) index values for interpolation in ``ParT`` (which must be + 3D). - This command is valid in any processor. + Notes + ----- + Forms an array parameter (of type ARRAY) by interpolating values of an array parameter (of type + TABLE) at specified table index locations according to: ``ParR`` = f( ``ParT``, ``Parl``, ``ParJ`` + , ``ParK`` ) where ``ParT`` is the type TABLE array parameter, and ``ParI``, ``ParJ``, ``ParK`` + are the type ARRAY array parameter vectors of index values for interpolation in ``ParT``. See the + :ref:`dim` command for TABLE and ARRAY declaration types. Linear interpolation is used. The starting + array element number for the TABLE array ( ``ParT`` ) is not used (but a value must be input). + Starting array element numbers must be defined for each array parameter vector if it does not start + at the first location. For example, :ref:`vitrp` ,R(5),TAB(1,1),X(2),Y(4) uses the second element of + X and the fourth element of Y as index values (row and column) for a 2D interpolation in TAB and + stores the result in the fifth element of R. Operations continue on successive array elements ( + :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. Absolute values and + scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be + cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. This command is valid in any + processor. """ - command = f"*VOPER,{parr},{par1},{oper},{par2},{con1},{con2}" + command = f"*VITRP,{parr},{part},{pari},{parj},{park}" return self.run(command, **kwargs) - def starvplot( + def vabs( self, - parx="", - pary="", - y2="", - y3="", - y4="", - y5="", - y6="", - y7="", - y8="", + kabsr: str = "", + kabs1: str = "", + kabs2: str = "", + kabs3: str = "", **kwargs, ): - r"""Graphs columns (vectors) of array parameters. + r"""Applies the absolute value function to array parameters. - Mechanical APDL Command: `\*VPLOT `_ + Mechanical APDL Command: `\*VABS `_ Parameters ---------- - parx : str - Name of the array parameter whose column vector values will be the abscissa of the graph. If - blank, row subscript numbers are used instead. ``ParX`` is not sorted by the program. + kabsr : str + Absolute value of results parameter: - pary : str - Name of the array parameter whose column vector values will be graphed against the ``ParX`` - values. + * ``0`` - Do not take absolute value of results parameter (ParR). + * ``1`` - Take absolute value. - y2, y3, y4, . . ., y8 : str - Additional column subscript of the ``ParY`` array parameter whose values are to be graphed - against the ``ParX`` values. + kabs1 : str + Absolute value of first parameter: - Notes - ----- - The column to be graphed and the starting row for each array parameter must be specified as subscripts. Additional columns of the ``ParY`` array parameter may be graphed by specifying column numbers for ``Y2``, ``Y3``, ..., ``Y8`` . For example, :ref:`starvplot` ,TIME (4,6), DISP (8,1),2,3 specifies that the 1st, 2nd, and 3rd columns of array parameter DISP (all starting at row 8) are to be graphed against the 6th column of array parameter TIME (starting at row 4). The columns are graphed from the starting row to their maximum extent. See the :ref:`vlen` and :ref:`vmask` commands to limit or skip data to be graphed. The array parameters specified on the :ref:`starvplot` command must be of the same type (type ARRAY or TABLE; ( :ref:`dim` ). Arrays of type TABLE are graphed as continuous curves. Arrays of type ARRAY is displayed in bar chart fashion. + * ``0`` - Do not take absolute value of first parameter (Par1 or ParI). + * ``1`` - Take absolute value. + + kabs2 : str + Absolute value of second parameter: - The normal curve labeling scheme for :ref:`starvplot` is to label curve 1 "COL 1", curve 2 "COL 2" and so on. You can use the :ref:`gcolumn` command to apply user-specified labels (8 characters maximum) to your curves. See `Modifying Curve Labels `_ in the `Ansys Parametric Design Language Guide `_ for more information on using :ref:`gcolumn` . + * ``0`` - Do not take absolute value of second parameter (Par2 or ParJ). + * ``1`` - Take absolute value. - Caret 243? - When a graph plot reaches minimum or maximum y-axis limits, the program indicates the condition by clipping the graph. The clip appears as a horizontal magenta line. Mechanical APDL calculates y-axis limits automatically; however, you can modify the (YMIN and YMAX) limits via the :ref:`yrange` command. + kabs3 : str + Absolute value of third parameter: + * ``0`` - Do not take absolute value of third parameter (Par3 or ParK). + * ``1`` - Take absolute value. + + Notes + ----- + Applies an absolute value to parameters used in certain \*V ``XX`` and \*M ``XX`` operations. + Typical absolute value applications are of the form: ParR = \|f(\|Par1\|)\| or ParR = \|(\|Par1\| o + \|Par2\|)\| The absolute values are applied to each input parameter value before the operation and to + the result value after the operation. Absolute values are applied before the scale factors so that + negative scale factors may be used. The absolute value settings are `reset` to the default (no + absolute value) after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. This command is valid in any processor. """ - command = f"*VPLOT,{parx},{pary},{y2},{y3},{y4},{y5},{y6},{y7},{y8}" + command = f"*VABS,{kabsr},{kabs1},{kabs2},{kabs3}" return self.run(command, **kwargs) def starvput( self, - parr="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", - kloop="", + parr: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", + kloop: str = "", **kwargs, ): r"""Restores array parameter values into the Mechanical APDL database. @@ -1101,25 +1113,25 @@ def starvput( it1num : str The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown - in the ``IT1NUM`` columns of the table below. Some ``Item1`` labels do not require an - ``IT1NUM`` value. + in the ``IT1NUM`` columns of the table below. Some ``Item1`` labels do not require an ``IT1NUM`` + value. - item2, it2num : str + item2 : str + A second set of item labels and numbers to further qualify the item for which data is to be + stored. Most items do not require this level of information. + + it2num : str A second set of item labels and numbers to further qualify the item for which data is to be stored. Most items do not require this level of information. kloop : str Field to be looped on: - * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). - - * ``3`` - Loop on the ``Item1`` field. - - * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM`` . - - * ``5`` - Loop on the ``Item2`` field. - - * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM`` . + * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). + * ``3`` - Loop on the ``Item1`` field. + * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM``. + * ``5`` - Loop on the ``Item2`` field. + * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM``. Notes ----- @@ -1148,7 +1160,7 @@ def starvput( - X, Y, or Z structural rotation. * - TEMP - - - Temperature. For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use TBOT, TE2, TE3, . . ., TTOP instead of TEMP. Alternative get functions: TEMP(N), TBOT(N), TE2(N), etc. + - Temperature. For SHELL131 and SHELL132 elements with KEYOPT(3) = 0 or 1, use TBOT, TE2, TE3,..., TTOP instead of TEMP. Alternative getfunctions: TEMP(N), TBOT(N), TE2(N), etc. * - PRES - - Pressure. @@ -1160,10 +1172,10 @@ def starvput( - Magnetic scalar potential. * - V - X, Y, Z - - X, Y, or Z fluid velocity. X, Y, or Z nodal velocity in a transient structural analysis (analysis with :ref:`antype` ,TRANS). + - X, Y, or Z fluid velocity. X, Y, or Z nodal velocity in a transient structural analysis (analysiswith :ref:`antype` ,TRANS). * - A - X, Y, Z - - X, Y, or Z magnetic vector potential. X, Y, or Z nodal acceleration in a transient structural analysis (analysis with :ref:`antype` ,TRANS). + - X, Y, or Z magnetic vector potential. X, Y, or Z nodal acceleration in a transient structuralanalysis (analysis with :ref:`antype` ,TRANS). * - CONC - - Concentration. @@ -1291,128 +1303,296 @@ def starvput( ) return self.run(command, **kwargs) - def vscfun(self, parr="", func="", par1="", **kwargs): - r"""Determines properties of an array parameter. + def vfun( + self, + parr: str = "", + func: str = "", + par1: str = "", + con1: str = "", + con2: str = "", + con3: str = "", + **kwargs, + ): + r"""Performs a function on a single array parameter. - Mechanical APDL Command: `\*VSCFUN `_ + Mechanical APDL Command: `\*VFUN `_ Parameters ---------- parr : str - The name of the resulting scalar parameter. See :ref:`starset` for name restrictions. + The name of the resulting numeric array parameter vector. See :ref:`starset` for name + restrictions. func : str - Functions: + Function to be performed: + + * ``ACOS`` - Arccosine: ACOS( ``Par1`` ). + * ``ASIN`` - Arcsine: ASIN( ``Par1`` ). + * ``ASORT`` - Par1 is sorted in ascending order. :ref:`vcol`, :ref:`vmask`, :ref:`vcum`, and + :ref:`vlen` ,,NINC do not apply. :ref:`vlen` ,NROW does apply. + * ``ATAN`` - Arctangent: ATAN( ``Par1`` ). + * ``COMP`` - Compress: Selectively compresses data set. "True" ( :ref:`vmask` ) values of ``Par1`` + (or row positions to be considered according to the ``NINC`` value on the :ref:`vlen` command) are + written in compressed form to ``ParR``, starting at the specified position. + * ``COPY`` - Copy: ``Par1`` copied to ``ParR``. + * ``COS`` - Cosine: COS( ``Par1`` ). + * ``COSH`` - Hyperbolic cosine: COSH( ``Par1`` ). + * ``DIRCOS`` - Direction cosines of the principal stresses ( ``n`` X9). ``Par1`` contains the ``n`` + X6 component stresses for the ``n`` locations of the calculations. + * ``DSORT`` - ``Par1`` is sorted in descending order. :ref:`vcol`, :ref:`vmask`, :ref:`vcum`, and + :ref:`vlen` ,,NINC do not apply. :ref:`vlen` ,NROW does apply. + * ``EULER`` - Euler angles of the principal stresses ( ``n`` X3). ``Par1`` contains the ``n`` X6 + component stresses for the ``n`` locations of the calculations. + * ``EXP`` - Exponential: EXP( ``Par1`` ). + * ``EXPA`` - Expand: Reverse of the COMP function. All elements of ``Par1`` (starting at the + position specified) are written in expanded form to corresponding "true" ( :ref:`vmask` ) + positions (or row positions to be considered according to the ``NINC`` value on the :ref:`vlen` + command) of ``ParR``. + * ``LOG`` - Natural logarithm: LOG( ``Par1`` ). + * ``LOG10`` - Common logarithm: LOG10( ``Par1`` ). + * ``NINT`` - Nearest integer: 2.783 becomes 3.0, -1.75 becomes -2.0. + * ``NOT`` - Logical complement: values :math:`` 0.0 (false) become 1.0 (true). Values > 0.0 + (true) become0.0 (false). + * ``PRIN`` - Principal stresses ( ``n`` X5). ``Par1`` contains the ``n`` X6 component stresses for + the ``n`` locations of the calculations. + * ``PWR`` - Power function: ``Par1`` \*\* ``CON1``. Exponentiation of any negative number in the + vector ``Par1`` to a non-integer power is performed by exponentiating the positive number and + prepending the minus sign. For example, -4\*\*2.3 is -(4\*\*2.3). + * ``SIN`` - Sine: SIN( ``Par1`` ). + * ``SINH`` - Hyperbolic sine: SINH( ``Par1`` ). + * ``SQRT`` - Square root: SQRT( ``Par1`` ). + * ``TAN`` - Tangent: TAN( ``Par1`` ). + * ``TANH`` - Hyperbolic tangent: TANH( ``Par1`` ). + * ``TANG`` - Tangent to a path at a point: the slope at a point is determined by linear + interpolation half way between the previous and next points. Points are assumed to be in the + global Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 + consecutive columns of data, with the columns containing the x, y, and z coordinate locations, + respectively, of the points). Only the starting row index and the column index for the x + coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed to + begin in the corresponding next columns, such as A(1,2) and A(1,3). The tangent result, ``ParR`` , + must also have 3 consecutive columns of data and will contain the tangent direction vector + (normalized to 1.0); such as 1,0,0 for an x-direction vector. + * ``NORM`` - Normal to a path and an input vector at a point: determined from the cross-product of + the calculated tangent vector (see TANG) and the input direction vector (with the i, j, and k + components input as ``CON1``, ``CON2``, and ``CON3`` ). Points are assumed to be in the global + Cartesian coordinate system. Path points are specified in array ``Par1`` (having 3 consecutive + columns of data, with the columns containing the x, y, and z coordinate locations, respectively, + of the points). Only the starting row index and the column index for the x coordinates are + specified, such as A(1,1). The y and z coordinates of the vector are assumed to begin in the + corresponding next columns, such as A(1,2) and A(1,3). The normal result, ``ParR``, must also + have 3 consecutive columns of data and will contain the normal direction vector (normalized to + 1.0); such as 1,0,0 for an x-direction vector. + * ``LOCAL`` - Transforms global Cartesian coordinates of a point to the coordinates of a specified + system: points to be transformed are specified in array ``Par1`` (having 3 consecutive columns of + data, with the columns containing the x, y, and z global Cartesian coordinate locations, + respectively, of the points). Only the starting row index and the column index for the x + coordinates are specified, such as A(1,1). The y and z coordinates of the vector are assumed to + begin in the corresponding next columns, such as A(1,2) and A(1,3). Results are transformed to + coordinate system ``CON1`` (which may be any valid coordinate system number, such as 1,2,11,12, + etc.). The transformed result, ``ParR``, must also have 3 consecutive columns of data and will + contain the corresponding transformed coordinate locations. + * ``GLOBAL`` - Transforms specified coordinates of a point to global Cartesian coordinates: points + to be transformed are specified in array ``Par1`` (having 3 consecutive columns of data, with the + columns containing the local coordinate locations (x, y, z or r, θ, z or etc.) of the + points). Only the starting row index and the column index for the x coordinates are specified, + such as A(1,1). The y and z coordinates (or θ and z, or etc.) of the vector are assumed to + begin in the corresponding next columns, such as A(1,2) and A(1,3). Local coordinate locations are + assumed to be in coordinate system ``CON1`` (which may be any valid coordinate system number, such + as 1,2,11,12, etc.). The transformed result, ``ParR``, must also have 3 consecutive columns of + data, with the columns containing the global Cartesian x, y, and z coordinate locations, + respectively. - * ``MAX`` - Maximum: the maximum ``Par1`` array element value. + par1 : str + Array parameter vector in the operation. - * ``MIN`` - Minimum: the minimum ``Par1`` array element value. + con1 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). - * ``LMAX`` - Index location of the maximum ``Par1`` array element value. Array ``Par1`` is - searched starting from its specified index. + con2 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). - * ``LMIN`` - Index location of the minimum ``Par1`` array element value. Array ``Par1`` is - searched starting from its specified index. + con3 : str + Constants (used only with the PWR, NORM, LOCAL, and GLOBAL functions). - * ``FIRST`` - Index location of the first nonzero value in array ``Par1`` . Array ``Par1`` - is - searched starting from its specified index. + Notes + ----- + Operates on one input array parameter vector and produces one output array parameter vector + according to: ``ParR`` = f( ``Par1`` ) where the functions (f) are described below. Functions are + based on the standard FORTRAN definitions where possible. Out-of-range function results (or results + with exponents whose magnitudes are approximately greater than 32 or less than -32) produce a zero + value. Input and output for angular functions may be radians (default) or degrees ( :ref:`afun` ). + ``ParR`` may be the same as ``Par1``. Starting array element numbers must be defined for each array + parameter vector if it does not start at the first location. For example, :ref:`vfun` ,A,SQRT,B(5) + takes the square root of the fifth element of B and stores the result in the first element of A. + Operations continue on successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default + being all successive elements. Absolute values and scale factors may be applied to all parameters ( + :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). Skipping array elements via + :ref:`vmask` or :ref:`vlen` for the TANG and NORM functions skips only the writing of the results + (skipped array element data are used in all calculations). See the :ref:`voper` command for details. + This command is valid in any processor. + """ + command = f"*VFUN,{parr},{func},{par1},{con1},{con2},{con3}" + return self.run(command, **kwargs) - * ``LAST`` - Index location of the last nonzero value in array ``Par1`` . Array ``Par1`` is - searched starting from its specified index. + def vfact( + self, + factr: str = "", + fact1: str = "", + fact2: str = "", + fact3: str = "", + **kwargs, + ): + r"""Applies a scale factor to array parameters. + + Mechanical APDL Command: `\*VFACT `_ - * ``SUM`` - Sum: ``Par1`` (the summation of the ``Par1`` array element values). + Parameters + ---------- + factr : str + Scale factor applied to results (ParR) parameter. Defaults to 1.0. - * ``MEDI`` - Median: value of ``Par1`` at which there are an equal number of values above - and - below. + fact1 : str + Scale factor applied to first parameter (Par1 or ParI). Defaults to 1.0. - * ``MEAN`` - Mean: (σ Par1)/NUM, where NUM is the number of summed values. + fact2 : str + Scale factor applied to second parameter (Par2 or ParJ). Defaults to 1.0. - * ``VARI`` - Variance: (σ (( ``Par1`` -MEAN)\*\*2))/NUM. + fact3 : str + Scale factor applied to third parameter (Par3 or ParK). Defaults to 1.0. - * ``STDV`` - Standard deviation: square root of VARI. + Notes + ----- + Applies a scale factor to parameters used in certain \*V ``XX`` and \*M ``XX`` operations. Typical + scale factor applications are of the form: ParR = ``FACTR`` \*f( ``FACT1`` \*Par1) or ParR = + ``FACTR`` \*(( ``FACT1`` \*Par1) o ( ``FACT2`` \*Par2)) The factors are applied to each input + parameter value before the operation and to the result value after the operation. The scale factor + settings are `reset` to the default (1.0) after each \*V ``XX`` or \*M ``XX`` operation. Use + :ref:`vstat` to list settings. This command is valid in any processor. + """ + command = f"*VFACT,{factr},{fact1},{fact2},{fact3}" + return self.run(command, **kwargs) - * ``RMS`` - Root-mean-square: square root of (σ ( ``Par1`` \*\*2))/NUM. + def vcum(self, key: str = "", **kwargs): + r"""Allows array parameter results to add to existing results. - * ``NUM`` - Number: the number of summed values (masked values are not counted). + Mechanical APDL Command: `\*VCUM `_ - par1 : str - Array parameter vector in the operation. + Parameters + ---------- + key : str + Accumulation key: + + * ``0`` - Overwrite results. + * ``1`` - Add results to the current value of the results parameter. Notes ----- - Operates on one input array parameter vector and produces one output scalar parameter according to: ``ParR`` = f( ``Par1`` ) + Allows results from certain \*V ``XX`` and \*M ``XX`` operations to overwrite or add to existing + results. The cumulative operation is of the form: ParR = ParR + ParR(Previous) The cumulative + setting is `reset` to the default (overwrite) after each \*V ``XX`` or \*M ``XX`` operation. Use + :ref:`vstat` to list settings. This command is valid in any processor. + """ + command = f"*VCUM,{key}" + return self.run(command, **kwargs) - where the functions (f) are described below. The starting array element number must be defined for the array parameter vector. For example, :ref:`vscfun` ,MU,MEAN,A(1) finds the mean of the A vector values, starting from the first value and stores the result as parameter MU. Operations use successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive array elements. Absolute values and scale factors may be applied to all parameters ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. + def vedit(self, par: str = "", **kwargs): + r"""Allows numerical array parameters to be graphically edited. - This command is valid in any processor. + Mechanical APDL Command: `\*VEDIT `_ + + Parameters + ---------- + par : str + Name of the array parameter to be edited. + + Notes + ----- + Invokes a graphical editing system that displays array parameter values in matrix form, and allows + the use of the mouse to edit individual values. The starting array subscripts must be defined, such + as :ref:`vedit` ,A(4,6,1), to indicate the section of the array to be edited. The array section + starts at the specified array element and continues to the maximum extent of the array parameter. + Row and column index values may be set or changed in any plane, and those values will be applied to + all planes. The menu system must be on ( :ref:`menu` ) when this command is issued. Graphical + editing is not available for character array parameters. The :ref:`vedit` command can not be used in + a macro or other secondary input file. This command is not applicable to 4- or 5-D arrays. This + command is valid in any processor. """ - command = f"*VSCFUN,{parr},{func},{par1}" + command = f"*VEDIT,{par}" return self.run(command, **kwargs) - def vstat(self, **kwargs): - r"""Lists the current specifications for the array parameters. + def vlen(self, nrow: str = "", ninc: str = "", **kwargs): + r"""Specifies the number of rows to be used in array parameter operations. - Mechanical APDL Command: `\*VSTAT `_ + Mechanical APDL Command: `\*VLEN `_ + + Parameters + ---------- + nrow : str + Number of rows to be used with the \*V ``XX`` or \*M ``XX`` operations. Defaults to the number + of rows needed to fill the result array. + + ninc : str + Perform the operation on every ``NINC`` row (defaults to 1). Notes ----- - Lists the current specifications for the :ref:`vabs`, :ref:`vcol`, :ref:`vcum`, :ref:`vfact`, :ref:`vlen`, and :ref:`vmask` commands. - - This command is valid in any processor. + Specifies the number of rows to be used in array parameter operations. The size of the submatrix + used is determined from the upper left starting array element (defined on the operation command) to + the lower right array element (defined by the number of rows on this command and the number of + columns on the :ref:`vcol` command). ``NINC`` allows skipping row operations for some operation + commands. Skipped rows are included in the row count. The starting row number must be defined on the + operation command for each parameter read and for the result written. The default ``NROW`` is + calculated from the maximum number of rows of the result array (the :ref:`dim` row dimension) minus + the starting location + 1. For example, :ref:`dim` ,R,,10 and a starting location of R(7) gives a + default of 4 loops (filling R(7), R(8), R(9), and R(10)). Repeat operations automatically terminate + at the last row of the result array. Existing values in the rows and columns of the results matrix + remain unchanged where not overwritten by the requested input or operation values. The stride ( + ``NINC`` ) allows operations to be performed at regular intervals. It has no effect on the total + number of row operations. Skipped operations retain the previous result. For example, :ref:`dim` + ,R,,6, with a starting location of R(1), ``NROW`` = 10, and ``NINC`` = 2 calculates values for + locations R(1), R(3), and R(5) and retains values for locations R(2), R(4), and R(6). A more general + skip control may be done by masking ( :ref:`vmask` ). The row control settings are `reset` to the + defaults after each \*V ``XX`` or \*M ``XX`` operation. Use :ref:`vstat` to list settings. This + command is valid in any processor. """ - command = f"*VSTAT" + command = f"*VLEN,{nrow},{ninc}" return self.run(command, **kwargs) - def vwrite( + def directory( self, - par1="", - par2="", - par3="", - par4="", - par5="", - par6="", - par7="", - par8="", - par9="", - par10="", - par11="", - par12="", - par13="", - par14="", - par15="", - par16="", - par17="", - par18="", - par19="", + strarray: str = "", + filename: str = "", + ext: str = "", + directory: str = "", **kwargs, ): - r"""Writes data to a file in a formatted sequence. + r"""Put the file names in the current directory into a string parameter array. - Mechanical APDL Command: `\*VWRITE `_ + Mechanical APDL Command: `/DIRECTORY `_ Parameters ---------- - par1, par2, par3, . . ., par19 : str - You can write up to 19 parameters (or constants) at a time. Any `Par` values after a blank `Par` - value are ignored. If you leave them all blank, one line will be written (to write a title or a - blank line). If you input the keyword SEQU, a sequence of numbers (starting from 1) will be - written for that item. - - Notes - ----- - You use :ref:`vwrite` to write data to a file in a formatted sequence. Data items ( ``Par1``, ``Par2``, etc.) may be array parameters, scalar parameters, character parameters (scalar or array), or constants. You must evaluate expressions and functions in the data item fields before using the :ref:`vwrite` command, since initially they will be evaluated to a constant and remain constant throughout the operation. Unless a file is defined with the :ref:`cfopen` command, data is written to the standard output file. Data written to the standard output file may be diverted to a different file by first switching the current output file with the :ref:`output` command. You can also use the :ref:`mwrite` command to write data to a specified file. Both commands contain format descriptors on the line immediately following the command. The format descriptors can be in either FORTRAN or C format. - - You must enclose FORTRAN format descriptors in parentheses. They must immediately follow the :ref:`vwrite` command on a separate line of the same input file. Do not include the word FORMAT. The format must specify the number of fields to be written per line, the field width, the placement of the decimal point, etc. You should use one field descriptor for each data item written. The write operation uses your system's available FORTRAN FORMAT conventions (see your system FORTRAN manual). You can use any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) and alphanumeric format (A). Alphanumeric strings are limited to a maximum of 8 characters for any field (A8) using the FORTRAN format. Use the "C" format for string arrays larger than 8 characters. Integer (I) and list-directed (\*) descriptors may `not` be used. You can include text in the format as a quoted string. `The parentheses must be included in the format` and the format must not exceed 80 characters (including parentheses). The output line length is limited to 128 characters. + strarray : str + Name of the string array parameter which will hold the returned values. String array parameters + are similar to character arrays, but each array element can be as long as 128 characters. If the + string parameter does not exist, it will be created. The array will be created as: + \*DIM,StrArray,STRING,64,2,numFileName - The "C" format descriptors are used if the first character of the format descriptor line is not a left parenthesis. "C" format descriptors are up to 80 characters long, consisting of text strings and predefined "data descriptors" between the strings where numeric or alphanumeric character data will be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C for alphanumeric character data, and %/ for a line break. There must be one data descriptor for each specified value (8 maximum) in the order of the specified values. The enhanced formats described in :ref:`msg` may also be used. + filename : str + File name (64 characters maximum). Only files matching this name will be returned. The + ``FileName`` ALL may match any file name. - For array parameter items, you must define the starting array element number. Looping continues (incrementing the vector index number of each array parameter by one) each time you output a line, until the maximum array vector element is written. For example, :ref:`vwrite` ,A(1) followed by (F6.0) will write one value per output line, that is, A(1), A(2), A(3), A(4), etc. You write constants and scalar parameters with the same values for each loop. You can also control the number of loops and loop skipping with the :ref:`vlen` and :ref:`vmask` commands. The vector specifications :ref:`vabs`, :ref:`vfact`, and :ref:`vcum` do not apply to this command. If looping continues beyond the supplied data array's length, zeros will be output for numeric array parameters and blanks for character array parameters. For multi-dimensioned array parameters, only the first (row) subscript is incremented. See the :ref:`voper` command for details. If you are in the GUI, the :ref:`vwrite` command must be contained in an externally prepared file and read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). + ext : str + File name extension (8 characters maximum). Only files with an extension matching this name will + be returned. A blank or ALL will match any extension. - If ``Par`` is a table array name, the subscripts refer to the index numbers of the table and not the index values of its primary variables. See :ref:`starset` if you want to evaluate a table array at certain values of its primary variables for writing. + directory : str + The directory in which the files reside. The default is the current working directory. - This command is valid in any processor. + Notes + ----- + The :ref:`directory` command gets the file names in the current directory and puts them into a + string parameter array. Each file will be included in the array as a name-extension pair. """ - command = f"*VWRITE,{par1},{par2},{par3},{par4},{par5},{par6},{par7},{par8},{par9},{par10},{par11},{par12},{par13},{par14},{par15},{par16},{par17},{par18},{par19}" + command = f"/DIRECTORY,{strarray},{filename},{ext},{directory}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py b/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py index ac1fdeedac..20ec8c66ca 100644 --- a/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py +++ b/src/ansys/mapdl/core/_commands/apdl/encryption_decryption.py @@ -23,8 +23,77 @@ class EncryptionDecryption: + def encrypt(self, key: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Controls encryption of command input. + + Mechanical APDL Command: `/ENCRYPT `_ + + Parameters + ---------- + key : str + Encryption key used to encrypt the data (32-character maximum). A character parameter may be + used. If the key is unspecified, encryption is turned off. + + fname : str + Name of file (including directory path) where the encrypted commands are written (248-character + maximum for both file name and directory). An unspecified directory path defaults to the working + directory; in this case, you can use all 248 characters for the file name. + + ext : str + File name extension (eight-character maximum). + + Notes + ----- + This command opens the encrypted file specified by ``Fname`` and ``Ext`` for writing encrypted input + commands. Issuing this command results in a new file that overwrites any data in an existing file + by the same name. When the encrypted file is written, the first line in the file is ``/DECRYPT`` + ,PASSWORD,OPENSSL and the last line is ``/DECRYPT``. See `Encrypting Command Input and Other Data + `_ + :ref:`encrypt` and performing encryption and decryption. + """ + command = f"/ENCRYPT,{key},{fname},{ext}" + return self.run(command, **kwargs) + + def decrypt(self, key1: str = "", key2: str = "", **kwargs): + r"""Controls decryption of command input. + + Mechanical APDL Command: `/DECRYPT `_ + + Parameters + ---------- + key1 : str + Key to decrypt the encrypted input created by :ref:`encrypt`. The only valid label is PASSWORD. + + key2 : str + Key to decrypt the encrypted input or to set the global encryption key. The following are valid + inputs: If ``Key2`` = OPENSSL or is blank, then decryption commences and the previously set + global encryption key is used for decryption. If ``Key2`` has a value, then that value is set as + the global encryption key. If ``Key2`` = OFF, then the global encryption password previously set + by the command :ref:`decrypt`,PASSWORD, ``Key2`` is reset. + + Notes + ----- + When decrypting an encrypted input, ``/DECRYPT,PASSWORD,OPENSSL`` must appear as the first line of + the encrypted file. The line is inserted automatically when you issue :ref:`encrypt` to create the + encrypted file. To read an encrypted file, enter :ref:`decrypt` ,PASSWORD, ``Key2`` anywhere in the + standard input file to set the global encryption key. The encryption key must be set before reading + in the encrypted input. :ref:`decrypt` is also valid when entered in the Command Input Window of + the Mechanical APDL user interface. See `Encrypting Command Input and Other Data + `_ + :ref:`decrypt` and performing encryption and decryption. + """ + command = f"/DECRYPT,{key1},{key2}" + return self.run(command, **kwargs) + def dbdecrypt( - self, keya="", keyb="", datatype="", num1="", num2="", inc="", **kwargs + self, + keya: str = "", + keyb: str = "", + datatype: str = "", + num1: str = "", + num2: str = "", + inc: str = "", + **kwargs, ): r"""Controls decryption of material data in the database file. @@ -35,7 +104,7 @@ def dbdecrypt( keya : str Decryption key A (32-character maximum). This key is used to decrypt the data in a one-level encryption or to control access to the data in a two-level encryption. Leave this field blank if - you do not have key A. + you do not have key A. keyb : str Decryption key B (32-character maximum). This key is used to decrypt the data in a two-level @@ -44,23 +113,42 @@ def dbdecrypt( datatype : str Type of data to decrypt. Must be set to MAT for material data. - num1, num2, inc : str + num1 : str Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. - Notes - ----- - This command decrypts data in the database file. It must be issued before resuming the database file ( :ref:`resume` command). Only ``KeyA`` is required for a one-level encryption . For a `two-level encryption `_, inputting ``KeyB`` gives you partial access to the data. Inputting both ``KeyA`` and ``KeyB`` gives you full access. + num2 : str + Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. - For more information about using :ref:`dbdecrypt` in the encryption/decryption procedure, see `Encrypting Material Data `_ :ref:`dbencrypt` command. + inc : str + Decrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. - This command is valid in any processor. + Notes + ----- + This command decrypts data in the database file. It must be issued before resuming the database file + ( :ref:`resume` command). Only ``KeyA`` is required for a one-level encryption. For a `two-level + encryption + `_ + , inputting ``KeyB`` gives you partial access to the data. Inputting both ``KeyA`` and ``KeyB`` + gives you full access. For more information about using :ref:`dbdecrypt` in the + encryption/decryption procedure, see `Encrypting Material Data + `_ + :ref:`dbencrypt` command. This command is valid in any processor. """ command = f"/DBDECRYPT,{keya},{keyb},{datatype},{num1},{num2},{inc}" return self.run(command, **kwargs) def dbencrypt( - self, keya="", keyb="", datatype="", num1="", num2="", inc="", **kwargs + self, + keya: str = "", + keyb: str = "", + datatype: str = "", + num1: str = "", + num2: str = "", + inc: str = "", + **kwargs, ): r"""Controls encryption of material data in the database file. @@ -74,89 +162,34 @@ def dbencrypt( keyb : str Encryption key B (32-character maximum). This key is used to encrypt the data in a two-level - encryption . If ``KeyB`` is not specified, a one-level encryption is used to encrypt the data. + encryption. If ``KeyB`` is not specified, a one-level encryption is used to encrypt the data. datatype : str Type of data to encrypt. Must be set to MAT for material data. - num1, num2, inc : str + num1 : str Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. - Notes - ----- - This command encrypts data in the database file. It must be issued before saving the database file ( :ref:`save` command). - - For a one-level encryption, specify only ``KeyA`` and set ``NUM1`` to ALL. ( ``NUM2`` and ``INC`` are not used.) - - For a `two-level encryption `_, specify both ``KeyA`` and ``KeyB`` . Also specify ``NUM1``, ``NUM2``, and ``INC`` as needed. - - For more information about using :ref:`dbencrypt` in the encryption/decryption procedure, see `Encrypting Material Data `_ :ref:`dbdecrypt` command. - - This command is valid in any processor. - """ - command = f"/DBENCRYPT,{keya},{keyb},{datatype},{num1},{num2},{inc}" - return self.run(command, **kwargs) - - def decrypt(self, key1="", key2="", **kwargs): - r"""Controls decryption of command input. - - Mechanical APDL Command: `/DECRYPT `_ - - Parameters - ---------- - key1 : str - Key to decrypt the encrypted input created by :ref:`encrypt` . The only valid label is PASSWORD. - - key2 : str - Key to decrypt the encrypted input or to set the global encryption key. The following are valid - inputs: - - If ``Key2`` = OPENSSL or is blank, then decryption commences and the previously set global - encryption key is used for decryption. - If ``Key2`` has a value, then that value is set as the global encryption key. - If ``Key2`` = OFF, then the global encryption password previously set by the command - :ref:`decrypt`,PASSWORD, ``Key2`` is reset. - - Notes - ----- - When decrypting an encrypted input, ``/DECRYPT,PASSWORD,OPENSSL`` must appear as the first line of the encrypted file. The line is inserted automatically when you issue :ref:`encrypt` to create the encrypted file. - - To read an encrypted file, enter :ref:`decrypt` ,PASSWORD, ``Key2`` anywhere in the standard input file to set the global encryption key. The encryption key must be set before reading in the encrypted input. - - :ref:`decrypt` is also valid when entered in the Command Input Window of the Mechanical APDL user interface. - - See `Encrypting Command Input and Other Data `_ :ref:`decrypt` and performing encryption and decryption. - """ - command = f"/DECRYPT,{key1},{key2}" - return self.run(command, **kwargs) - - def encrypt(self, key="", fname="", ext="", **kwargs): - r"""Controls encryption of command input. - - Mechanical APDL Command: `/ENCRYPT `_ - - Parameters - ---------- - key : str - Encryption key used to encrypt the data (32-character maximum). A character parameter may be - used. If the key is unspecified, encryption is turned off. - - fname : str - Name of file (including directory path) where the encrypted commands are written (248-character - maximum for both file name and directory). An unspecified directory path defaults to the working - directory; in this case, you can use all 248 characters for the file name. + num2 : str + Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. - ext : str - File name extension (eight-character maximum). + inc : str + Encrypt materials from material number ``NUM1`` to ``NUM2`` (defaults to ``NUM1`` ) in steps of + ``INC`` (defaults to 1). If ``NUM1`` = ALL (default), ``NUM2`` and ``INC`` are ignored. Notes ----- - This command opens the encrypted file specified by ``Fname`` and ``Ext`` for writing encrypted input commands. - - Issuing this command results in a new file that overwrites any data in an existing file by the same name. When the encrypted file is written, the first line in the file is ``/DECRYPT`` ,PASSWORD,OPENSSL and the last line is ``/DECRYPT`` . - - See `Encrypting Command Input and Other Data `_ :ref:`encrypt` and performing encryption and decryption. + This command encrypts data in the database file. It must be issued before saving the database file ( + :ref:`save` command). For a one-level encryption, specify only ``KeyA`` and set ``NUM1`` to ALL. ( + ``NUM2`` and ``INC`` are not used.) For a `two-level encryption + `_ + , specify both ``KeyA`` and ``KeyB``. Also specify ``NUM1``, ``NUM2``, and ``INC`` as needed. For + more information about using :ref:`dbencrypt` in the encryption/decryption procedure, see + `Encrypting Material Data + `_ + :ref:`dbdecrypt` command. This command is valid in any processor. """ - command = f"/ENCRYPT,{key},{fname},{ext}" + command = f"/DBENCRYPT,{keya},{keyb},{datatype},{num1},{num2},{inc}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/macro_files.py b/src/ansys/mapdl/core/_commands/apdl/macro_files.py index 9d81d44891..286d35a91e 100644 --- a/src/ansys/mapdl/core/_commands/apdl/macro_files.py +++ b/src/ansys/mapdl/core/_commands/apdl/macro_files.py @@ -23,52 +23,262 @@ class MacroFiles: - def cfclos(self, **kwargs): - r"""Closes the "command" file. + def pmacro(self, **kwargs): + r"""Specifies that macro contents be written to the session log file. - Mechanical APDL Command: `\*CFCLOS `_ + Mechanical APDL Command: `/PMACRO `_ Notes ----- - This command is valid in any processor. + This command forces the contents of a macro or other input file to be written to ``Jobname.LOG``. It + is valid only within a macro or input file, and should be placed at the top of the file. + :ref:`pmacro` should be included in any macro or input file that calls GUI functions. """ - command = f"*CFCLOS" + command = f"/PMACRO" return self.run(command, **kwargs) - def cfopen(self, loc="", **kwargs): - r"""Opens a "command" file. + def psearch(self, pname: str = "", **kwargs): + r"""Specifies a directory to be searched for "unknown command" macro files. - Mechanical APDL Command: `\*CFOPEN `_ + Mechanical APDL Command: `/PSEARCH `_ + + Parameters + ---------- + pname : str + Path name (64 characters maximum, and must include the final delimiter) of the middle directory + to be searched. Defaults to the user home directory. If ``Pname`` = OFF, search only the program + and current working directories. If ``Pname`` = STAT, list the current middle directory and show + the ANSYS_MACROLIB setting. + + Notes + ----- + Specifies the pathname of a directory for file searches when reading unknown-command macro files. + The search for the files is typically from the program directory, then from the user home directory, + and then from the current working directory. The command allows the middle directory searched to be + other than the user home directory. This command is valid only at the Begin level. + """ + command = f"/PSEARCH,{pname}" + return self.run(command, **kwargs) + + def ulib(self, fname: str = "", ext: str = "", **kwargs): + r"""Identifies a macro library file. + + Mechanical APDL Command: `\*ULIB `_ Parameters ---------- fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - The file name defaults to ``Jobname`` . + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, + you can use all 248 characters for the file name. ext : str Filename extension (eight-character maximum). - The extension defaults to CMD if ``Fname`` is blank. - loc : str - Determines whether existing file will be overwritten or appended: + Notes + ----- + Identifies a macro library file for the :ref:`use` command. - * ```` - The existing file will be overwritten. + A library of macros allows blocks of often-used commands to be stacked and executed from a single + file. The macro blocks must be enclosed within block identifier and terminator lines as shown in + this example: Macro Blocks - * ``APPEND`` - The file will be appended to the existing file. + .. code:: - Notes - ----- - Mechanical APDL commands specified by the :ref:`cfwrite` command are written to the file opened by :ref:`cfopen` . Data processed with the :ref:`vwrite` command are also written to this file if the file is open when the :ref:`vwrite` command is issued. + ABC! Any valid alphanumeric name (32 characters maximum) + ! identifying this data block + ---! Mechanical APDL data-input commands + --- + --- + /EOF! Terminator for this data block + XYZ! Identify another data block (if desired) + ---! Mechanical APDL data-input commands + --- + --- + /EOF! Terminator for this data block + (etc.) + + To add comment lines to a macro block, place them anywhere `within` the macro block, including directly on the lines where the macro block identifier and the macro + block terminator appear as shown in the example. Do not place comment lines (or any other lines) + outside of a macro block. + + The name of the macro library file is identified for reading via :ref:`ulib` . The name of the macro block is identified via :ref:`use` . + + Commands within the macro block are copied to a temporary file (of the macro block name) during the :ref:`use` operation and executed as if a macro file of that name had been created. The temporary file is deleted after it has been used. - Issue the :ref:`cfclos` command to close the command file. + Macro block names should be acceptable file names (system-dependent) and should not match user- + created macro file names, as the user-created macro file is used first (if it exists) before the + library file is searched. + + Macro blocks may be stacked in any order. Branching ( :ref:`stargo` or :ref:`if` ) external to the macro block is not allowed. This command is valid in any processor. """ - command = f"*CFOPEN,{loc}" + command = f"*ULIB,{fname},{ext}" return self.run(command, **kwargs) - def cfwrite(self, command="", **kwargs): + def use( + self, + name: str = "", + arg1: str = "", + arg2: str = "", + arg3: str = "", + arg4: str = "", + arg5: str = "", + arg6: str = "", + arg7: str = "", + arg8: str = "", + arg9: str = "", + ar10: str = "", + ar11: str = "", + ar12: str = "", + ar13: str = "", + ar14: str = "", + ag15: str = "", + ar16: str = "", + ar17: str = "", + ar18: str = "", + **kwargs, + ): + r"""Executes a macro file. + + Mechanical APDL Command: `\*USE `_ + + Parameters + ---------- + name : str + Name (32 characters maximum, beginning with a letter) identifying the macro file or a macro + block on a macro library file. + + arg1 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg2 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg3 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg4 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg5 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg6 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg7 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg8 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + arg9 : str + Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through + AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters + enclosed in single quotes), parameters (numeric or character) or parametric expressions. See + below for additional details. + + ar10 : str + + ar11 : str + + ar12 : str + + ar13 : str + + ar14 : str + + ag15 : str + + ar16 : str + + ar17 : str + + ar18 : str + + Notes + ----- + Causes execution of a macro file called ``Name``, or, if not found, a macro block " ``Name`` " on + the macro library file ( :ref:`ulib` ). Argument values (numeric or character) are passed into the + file or block and substituted for local parameters ARG1, ARG2,..., AR18. The file ``Name`` may also + be executed as an "unknown command" (that is, without the :ref:`use` command name) as described + below. A macro is a sequence of Mechanical APDL commands (as many as needed) recorded in a file or in a + macro block in a library file (specified with the :ref:`ulib` command). The file or block is + typically executed via :ref:`use`. In addition to command, numerical and alphanumeric data, the + macro can include parameters which will be assigned numerical or alphanumerical character values + when the macro is used. Use of the macro can be repeated (within a do-loop, for example) with the + parameters incremented. A macro is defined within a run by enclosing a sequence of data input + commands between :ref:`create` and :ref:`end` commands. The data input commands are passive (not + executed) while being written to the macro file. The macro file (without :ref:`create` and + :ref:`end` ) can also be created external to Mechanical APDL. Up to 99 specially named scalar parameters, + ARG1 to AR99, are `locally` available to each macro: The prefix for the first nine parameters is + ARG, and the prefix for the remaining 90 parameters is AR. A local parameter is not affected by, nor + does it affect, other parameters, even those of the same name, which are used outside of the macro. + The only way a local parameter can affect, or be affected by, parameters outside the macro is if + values are passed out of, or into, the macro by an argument list. Parameters ARG1 through AR18 can + have their values (numeric or character) passed via the argument list on :ref:`use`. (ARG1 through + AR19 can be passed as arguments on the unknown-command macro.) Parameters AR19 through AR99 (AR20 + through AR99 in the unknown-command macro) are available solely for use within the macro; they + cannot be passed via an argument list. Local parameters are available to do-loops and to + :ref:`input` files processed within the macro. In addition to an ARG1--AR99 set for each macro, + another ARG1--AR99 set is available external to all macros, local to "non-macro" space. A macro is + exited after its last line is executed. Macros may be nested (such as a :ref:`use` or an unknown + command within a macro). Each nested macro has its own set of 99 local parameters. Only one set of + local parameters can be active at a time and that is the set corresponding to the macro currently + being executed or to the set external to all macros (if any). When a nested macro completes + execution, the previous set of local parameters once again becomes available. Issue + :ref:`starstatus` ,ARGX to view current macro parameter values. An alternate way of executing a + macro file is via the unknown-command route. If a command unknown to Mechanical APDL is entered, a search + for a file of that name (plus a ``.MAC`` suffix) is made. If the file exists, it is executed, if + not, the "unknown command" message is output. Thus, you can write your own commands in terms of + other Mechanical APDL commands. The procedure is similar to issuing :ref:`use` with the unknown command in + the ``Name`` field. For example, the command CMD ,10,20,30 is internally similar to :ref:`use` + ,CMD,10,20,30. The macro file named ``CMD.MAC`` is executed with the three parameters. The + :ref:`use` macro description also applies to the unknown-command macro, except that various + directories are searched and a suffix ( ``.MAC`` ) is assumed. Also, a macro library file is not + searched. A three-level directory search for the unknown-command macro file may be available. The + search order may be: 1) a high-level system directory, 2) the log-in directory, and 3) the local + (working) directory. Issue :ref:`psearch` to change the directory search path. For an unknown + command CMD, the first file named ``CMD.MAC`` found to exist in the search order is executed. The + command can be input in lower-, upper-, or mixed-case; however, it converts to uppercase + automatically before the file name search occurs. On systems that preserve the case as it was input, + a file matching the upper-case name is used first, followed by a file with the matching the lower- + case name, and finally a file matching the mixed-case name. All macro files placed in the ``apdl`` + directory must be upper-case. Because undocumented commands exist in Mechanical APDL, you should issue the + command intended for the macro file name to ensure that the unknown-command message is output in the + processor where it is to be used. If the macro is to be used in other processors, the other + processors must also be checked. This command is valid in any processor. + """ + command = f"*USE,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{ar10},{ar11},{ar12},{ar13},{ar14},{ag15},{ar16},{ar17},{ar18}" + return self.run(command, **kwargs) + + def cfwrite(self, command: str = "", **kwargs): r"""Writes a Mechanical APDL command (or similar string) to a "command" file. Mechanical APDL Command: `\*CFWRITE `_ @@ -82,68 +292,104 @@ def cfwrite(self, command="", **kwargs): Notes ----- - Writes a Mechanical APDL command (or similar string) to the file opened via :ref:`cfopen` . The ``Command`` string is not executed (except that numeric and character parameter substitution and operations (with imbedded \*, /, >, etc. characters) are performed before writing). + Writes a Mechanical APDL command (or similar string) to the file opened via :ref:`cfopen`. The ``Command`` + string is not executed (except that numeric and character parameter substitution and operations + (with imbedded \*, /, >, etc. characters) are performed before writing). When used with :ref:`get` + results and parameter substitution, a command can be created from results and then read back into + the Mechanical APDL program (or used elsewhere). For example, if the command :ref:`cfwrite` + ,BF,NNUM,TEMP,TVAL is used in a do-loop, where TVAL is a parameter value returned from the + :ref:`get` operation and NNUM is a specified or returned parameter value, a series of :ref:`bf` + commands, with numerical values substituted for the two parameters, will be written. To create a + file without parameter substitution, issue :ref:`create`. This command is valid in any processor. + """ + command = f"*CFWRITE,{command}" + return self.run(command, **kwargs) - When used with :ref:`get` results and parameter substitution, a command can be created from results and then read back into the Mechanical APDL program (or used elsewhere). For example, if the command :ref:`cfwrite` ,BF,NNUM,TEMP,TVAL is used in a do-loop, where TVAL is a parameter value returned from the :ref:`get` operation and NNUM is a specified or returned parameter value, a series of :ref:`bf` commands, with numerical values substituted for the two parameters, will be written. + def cfclos(self, **kwargs): + r"""Closes the "command" file. - To create a file without parameter substitution, issue :ref:`create` . + Mechanical APDL Command: `\*CFCLOS `_ + Notes + ----- This command is valid in any processor. """ - command = f"*CFWRITE,{command}" + command = f"*CFCLOS" return self.run(command, **kwargs) - def create(self, **kwargs): - r"""Opens (creates) a macro file. + def cfopen(self, fname: str = "", ext: str = "", loc: str = "", **kwargs): + r"""Opens a "command" file. - Mechanical APDL Command: `\*CREATE `_ + Mechanical APDL Command: `\*CFOPEN `_ Parameters ---------- fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - Do not use a directory path if file is to be read with the macro ``Name`` option of the - :ref:`use` command. + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. The file name defaults to ``Jobname``. ext : str - Filename extension (eight-character maximum). - ``Ext`` should not be used if file is to be read with the macro ``Name`` option of the - :ref:`use` command. + Filename extension (eight-character maximum). The extension defaults to CMD if ``Fname`` is blank. + + loc : str + Determines whether existing file will be overwritten or appended: + + * ```` - The existing file will be overwritten. + * ``APPEND`` - The file will be appended to the existing file. Notes ----- - See the :ref:`use` command for a discussion of macros. All commands following the :ref:`create` command, up to the :ref:`end` command, are written to the specified file without being executed. An existing file of the same name, if any, will be overwritten. Parameter values are not substituted for parameter names in the commands when the commands are written to the file. Use :ref:`cfwrite` to create a file if this is desired. The resulting macro may be executed with a :ref:`use` command (which also allows parameters to be passed into the macro) or a :ref:`input` command (which does not allow parameters to be passed in). Several macros may be stacked into a library file ( :ref:`ulib` ). You cannot use :ref:`create` within a DO loop. - - This command is valid in any processor. + Mechanical APDL commands specified by the :ref:`cfwrite` command are written to the file opened by + :ref:`cfopen`. Data processed with the :ref:`vwrite` command are also written to this file if the + file is open when the :ref:`vwrite` command is issued. Issue the :ref:`cfclos` command to close the + command file. This command is valid in any processor. """ - command = f"*CREATE" + command = f"*CFOPEN,{fname},{ext},{loc}" return self.run(command, **kwargs) - def end(self, **kwargs): - r"""Closes a macro file. + def create(self, fname: str = "", ext: str = "", **kwargs): + r"""Opens (creates) a macro file. - Mechanical APDL Command: `\*END `_ + Mechanical APDL Command: `\*CREATE `_ + + Parameters + ---------- + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. Do not use a directory path if file is to be read with the macro ``Name`` option of + the :ref:`use` command. + + ext : str + Filename extension (eight-character maximum). ``Ext`` should not be used if file is to be read with the macro ``Name`` option of + the :ref:`use` command. Notes ----- - Closes a file opened with :ref:`create` . The :ref:`end` command is an 8-character command (to differentiate it from :ref:`endif` ). If you add commented text on that same line but do not allow enough spaces between :ref:`end` and the "!" that indicates the comment text, the :ref:`end` will attempt to interpret the "!" as the 8th character and will fail. - - This command is valid in any processor. + See the :ref:`use` command for a discussion of macros. All commands following the :ref:`create` + command, up to the :ref:`end` command, are written to the specified file without being executed. An + existing file of the same name, if any, will be overwritten. Parameter values are not substituted + for parameter names in the commands when the commands are written to the file. Use :ref:`cfwrite` to + create a file if this is desired. The resulting macro may be executed with a :ref:`use` command + (which also allows parameters to be passed into the macro) or a :ref:`input` command (which does not + allow parameters to be passed in). Several macros may be stacked into a library file ( :ref:`ulib` + ). You cannot use :ref:`create` within a DO loop. This command is valid in any processor. """ - command = f"*END" + command = f"*CREATE,{fname},{ext}" return self.run(command, **kwargs) def msg( self, - lab="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", + lab: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", **kwargs, ): r"""Writes an output message via the Mechanical APDL message subroutine. @@ -155,35 +401,69 @@ def msg( lab : str Label for output and termination control: - * ``INFO`` - Writes the message with no heading (default). + * ``INFO`` - Writes the message with no heading (default). + * ``NOTE`` - Writes the message with a "NOTE" heading. + * ``WARN`` - Writes the message with a "WARNING" heading. Also writes the message to the errors + file, ``Jobname.ERR``. + * ``ERROR`` - Writes the message with a "ERROR" heading and causes run termination (if batch) at + earliest "clean exit" point. Also writes the message to the errors file, ``Jobname.ERR``. + * ``FATAL`` - Writes the message with a "FATAL ERROR" heading and causes run termination + immediately. Also writes the message to the errors file, ``Jobname.ERR``. + * ``UI`` - Writes the message with a "NOTE" heading and displays it in the message dialog box. This + option is most useful in GUI mode. + + val1 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - * ``NOTE`` - Writes the message with a "NOTE" heading. + val2 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - * ``WARN`` - Writes the message with a "WARNING" heading. Also writes the message to the - errors - file, ``Jobname.ERR`` . + val3 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - * ``ERROR`` - Writes the message with a "ERROR" heading and causes run termination (if - batch) at - earliest "clean exit" point. Also writes the message to the errors file, ``Jobname.ERR`` . + val4 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - * ``FATAL`` - Writes the message with a "FATAL ERROR" heading and causes run termination - immediately. Also writes the message to the errors file, ``Jobname.ERR`` . + val5 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - * ``UI`` - Writes the message with a "NOTE" heading and displays it in the message dialog - box. - This option is most useful in GUI mode. + val6 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. + + val7 : str + Numeric or alphanumeric character values to be included in message. Values may be the results of + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + nearest integer (NINT) function is used to form integers for the %I specifier. - val1, val2, val3, . . ., val8 : str + val8 : str Numeric or alphanumeric character values to be included in message. Values may be the results of - parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN + parameter evaluations. All numeric values are assumed to be double precision. The FORTRAN nearest integer (NINT) function is used to form integers for the %I specifier. Notes ----- - Allows writing an output message via the Mechanical APDL message subroutine. Also allows run termination control. This command is used only when contained in a prepared file read into the Mechanical APDL program (that is, :ref:`use`, :ref:`input`, etc.). A message format must immediately follow the :ref:`msg` command (on a separate line, without parentheses, as described below). + Allows writing an output message via the Mechanical APDL message subroutine. Also allows run termination + control. This command is used only when contained in a prepared file read into the Mechanical APDL program + (that is, :ref:`use`, :ref:`input`, etc.). A message format must immediately follow the :ref:`msg` command (on a separate line, without parentheses, as described below). - The message format may be up to 80 characters long, consisting of text strings and predefined "data descriptors" between the strings where numeric or alphanumeric character data are to be inserted. The normal descriptors are %I for integer data, %G for double precision data, %C for alphanumeric character data, and %/ for a line break. The corresponding FORTRAN data descriptors are I9, 1PG16.9 and A8, respectively. Each descriptor must be preceded by a blank. There must be one data descriptor for each specified value (8 maximum) in the order of the specified values. + The message format may be up to 80 characters long, consisting of text strings and predefined "data + descriptors" between the strings where numeric or alphanumeric character data are to be inserted. + The normal descriptors are %I for integer data, %G for double precision data, %C for alphanumeric + character data, and %/ for a line break. The corresponding FORTRAN data descriptors are I9, 1PG16.9 + and A8, respectively. Each descriptor must be preceded by a blank. There must be one data descriptor + for each specified value (8 maximum) in the order of the specified values. Enhanced descriptions may also be used: InformalTables need to be added. @@ -223,7 +503,7 @@ def msg( command = f"*MSG,{lab},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8}" return self.run(command, **kwargs) - def mkdir(self, dir="", **kwargs): + def mkdir(self, **kwargs): r"""Creates a directory. Mechanical APDL Command: `/MKDIR `_ @@ -232,58 +512,26 @@ def mkdir(self, dir="", **kwargs): ----- Creates a directory on the computer Mechanical APDL is currently running on. """ - command = f"/MKDIR,{dir}" - return self.run(command, **kwargs) - - def pmacro(self, **kwargs): - r"""Specifies that macro contents be written to the session log file. - - Mechanical APDL Command: `/PMACRO `_ - - Notes - ----- - This command forces the contents of a macro or other input file to be written to ``Jobname.LOG`` . It is valid only within a macro or input file, and should be placed at the top of the file. :ref:`pmacro` should be included in any macro or input file that calls GUI functions. - """ - command = f"/PMACRO" - return self.run(command, **kwargs) - - def psearch(self, pname="", **kwargs): - r"""Specifies a directory to be searched for "unknown command" macro files. - - Mechanical APDL Command: `/PSEARCH `_ - - Parameters - ---------- - pname : str - Path name (64 characters maximum, and must include the final delimiter) of the middle directory - to be searched. Defaults to the user home directory. If ``Pname`` = OFF, search only the program - and current working directories. If ``Pname`` = STAT, list the current middle directory and - show the ANSYS_MACROLIB setting. - - Notes - ----- - Specifies the pathname of a directory for file searches when reading unknown-command macro files. - - The search for the files is typically from the program directory, then from the user home directory, and then from the current working directory. The command allows the middle directory searched to be other than the user home directory. - - This command is valid only at the Begin level. - """ - command = f"/PSEARCH,{pname}" + command = f"/MKDIR" return self.run(command, **kwargs) - def rmdir(self, dir="", **kwargs): - r"""Removes (deletes) a directory. + def end(self, **kwargs): + r"""Closes a macro file. - Mechanical APDL Command: `/RMDIR `_ + Mechanical APDL Command: `\*END `_ Notes ----- - Removes a directory on the computer on which Mechanical APDL is currently running. No warning or prompt is given, so use with extreme caution. + Closes a file opened with :ref:`create`. The :ref:`end` command is an 8-character command (to + differentiate it from :ref:`endif` ). If you add commented text on that same line but do not allow + enough spaces between :ref:`end` and the "!" that indicates the comment text, the :ref:`end` will + attempt to interpret the "!" as the 8th character and will fail. This command is valid in any + processor. """ - command = f"/RMDIR,{dir}" + command = f"*END" return self.run(command, **kwargs) - def slashtee(self, label="", **kwargs): + def slashtee(self, label: str = "", fname: str = "", ext: str = "", **kwargs): r"""Writes a list of commands to a specified file at the same time that the commands are being executed. Mechanical APDL Command: `/TEE `_ @@ -293,20 +541,19 @@ def slashtee(self, label="", **kwargs): label : str Specifies how Mechanical APDL is to interpret this :ref:`slashtee` command: - * ``NEW`` - Signals the beginning of the command text that is to be written to ``Fname`` . - If + * ``NEW`` - Signals the beginning of the command text that is to be written to ``Fname``. If ``Fname`` already exists, specifying NEW causes the contents of ``Fname`` to be overwritten. - - * ``APPEND`` - Indicates that you want to append to ``Fname`` the command text that follows. - - * ``END`` - Signals the end of the command text that is to be written to or appended to - ``Fname`` . + * ``APPEND`` - Indicates that you want to append to ``Fname`` the command text that follows. + * ``END`` - Signals the end of the command text that is to be written to or appended to ``Fname``. fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. + ext : str - Filename extension (eight-character maximum). - If you plan to execute the file as if it were a Mechanical APDL command, use the extension ``.mac`` . + Filename extension (eight-character maximum). If you plan to execute the file as if it were a Mechanical APDL command, use the extension + ``.mac``. Notes ----- @@ -342,132 +589,18 @@ def slashtee(self, label="", **kwargs): This command is valid in any processor, but only during an interactive run. """ - command = f"/TEE,{label}" - return self.run(command, **kwargs) - - def ulib(self, fname="", ext="", **kwargs): - r"""Identifies a macro library file. - - Mechanical APDL Command: `\*ULIB `_ - - Parameters - ---------- - fname : str - File name and directory path (248 characters maximum, including the characters needed for the - directory path). An unspecified directory path defaults to the working directory; in this case, - you can use all 248 characters for the file name. - - ext : str - Filename extension (eight-character maximum). - - Notes - ----- - Identifies a macro library file for the :ref:`use` command. - - A library of macros allows blocks of often-used commands to be stacked and executed from a single file. The macro blocks must be enclosed within block identifier and terminator lines as shown in this example: Macro Blocks - - .. code:: - - ABC! Any valid alphanumeric name (32 characters maximum) - ! identifying this data block - ---! Mechanical APDL data-input commands - --- - --- - /EOF! Terminator for this data block - XYZ! Identify another data block (if desired) - ---! Mechanical APDL data-input commands - --- - --- - /EOF! Terminator for this data block - (etc.) - - To add comment lines to a macro block, place them anywhere `within` the macro block, including directly on the lines where the macro block identifier and the macro block terminator appear as shown in the example. Do not place comment lines (or any other lines) outside of a macro block. - - The name of the macro library file is identified for reading via :ref:`ulib` . The name of the macro block is identified via :ref:`use` . - - Commands within the macro block are copied to a temporary file (of the macro block name) during the :ref:`use` operation and executed as if a macro file of that name had been created. The temporary file is deleted after it has been used. - - Macro block names should be acceptable file names (system-dependent) and should not match user-created macro file names, as the user-created macro file is used first (if it exists) before the library file is searched. - - Macro blocks may be stacked in any order. Branching ( :ref:`stargo` or :ref:`if` ) external to the macro block is not allowed. - - This command is valid in any processor. - """ - command = f"*ULIB,{fname},{ext}" + command = f"/TEE,{label},{fname},{ext}" return self.run(command, **kwargs) - def use( - self, - name="", - arg1="", - arg2="", - arg3="", - arg4="", - arg5="", - arg6="", - arg7="", - arg8="", - arg9="", - ar10="", - ar11="", - ar12="", - ar13="", - ar14="", - ag15="", - ar16="", - ar17="", - ar18="", - **kwargs, - ): - r"""Executes a macro file. - - Mechanical APDL Command: `\*USE `_ - - Parameters - ---------- - name : str - Name (32 characters maximum, beginning with a letter) identifying the macro file or a macro - block on a macro library file. + def rmdir(self, **kwargs): + r"""Removes (deletes) a directory. - arg1, arg2, arg3, . . ., ar18 : str - Values passed into the file or block where the parameters ARG1 through ARG9 and AR10 through - AR18 are referenced. Values may be numbers, alphanumeric character strings (up to 32 characters - enclosed in single quotes), parameters (numeric or character) or parametric expressions. See - below for additional details. + Mechanical APDL Command: `/RMDIR `_ Notes ----- - Causes execution of a macro file called ``Name``, or, if not found, a macro block " ``Name`` " on the macro library file ( :ref:`ulib` ). Argument values (numeric or character) are passed into the file or block and substituted for local parameters ARG1, ARG2, ..., AR18. The file ``Name`` may also be executed as an "unknown command" (that is, without the :ref:`use` command name) as described below. - - A macro is a sequence of Mechanical APDL commands (as many as needed) recorded in a file or in a macro block in a library file (specified with the :ref:`ulib` command). The file or block is typically executed via :ref:`use` . In addition to command, numerical and alphanumeric data, the macro can include parameters which will be assigned numerical or alphanumerical character values when the macro is used. Use of the macro can be repeated (within a do-loop, for example) with the parameters incremented. - - A macro is defined within a run by enclosing a sequence of data input commands between :ref:`create` and :ref:`end` commands. The data input commands are passive (not executed) while being written to the macro file. The macro file (without :ref:`create` and :ref:`end` ) can also be created external to Mechanical APDL. - - Up to 99 specially named scalar parameters, ARG1 to AR99, are `locally` available to each macro: - - The prefix for the first nine parameters is ARG, and the prefix for the remaining 90 parameters is - AR. - A local parameter is not affected by, nor does it affect, other parameters, even those of the same - name, which are used outside of the macro. The only way a local parameter can affect, or be affected - by, parameters outside the macro is if values are passed out of, or into, the macro by an argument - list. - Parameters ARG1 through AR18 can have their values (numeric or character) passed via the argument - list on :ref:`use`. (ARG1 through AR19 can be passed as arguments on the unknown-command macro.) - Parameters AR19 through AR99 (AR20 through AR99 in the unknown-command macro) are available solely - for use within the macro; they cannot be passed via an argument list. - Local parameters are available to do-loops and to :ref:`input` files processed within the macro. In - addition to an ARG1--AR99 set for each macro, another ARG1--AR99 set is available external to all - macros, local to "non-macro" space. - - A macro is exited after its last line is executed. Macros may be nested (such as a :ref:`use` or an unknown command within a macro). Each nested macro has its own set of 99 local parameters. Only one set of local parameters can be active at a time and that is the set corresponding to the macro currently being executed or to the set external to all macros (if any). When a nested macro completes execution, the previous set of local parameters once again becomes available. Issue :ref:`starstatus` ,ARGX to view current macro parameter values. - - An alternate way of executing a macro file is via the unknown-command route. If a command unknown to Mechanical APDL is entered, a search for a file of that name (plus a ``.MAC`` suffix) is made. If the file exists, it is executed, if not, the "unknown command" message is output. Thus, you can write your own commands in terms of other Mechanical APDL commands. The procedure is similar to issuing :ref:`use` with the unknown command in the ``Name`` field. For example, the command CMD ,10,20,30 is internally similar to :ref:`use` ,CMD,10,20,30. The macro file named ``CMD.MAC`` is executed with the three parameters. The :ref:`use` macro description also applies to the unknown-command macro, except that various directories are searched and a suffix ( ``.MAC`` ) is assumed. Also, a macro library file is not searched. - - A three-level directory search for the unknown-command macro file may be available. The search order may be: 1) a high-level system directory, 2) the log-in directory, and 3) the local (working) directory. Issue :ref:`psearch` to change the directory search path. For an unknown command CMD, the first file named ``CMD.MAC`` found to exist in the search order is executed. The command can be input in lower-, upper-, or mixed-case; however, it converts to uppercase automatically before the file name search occurs. On systems that preserve the case as it was input, a file matching the upper-case name is used first, followed by a file with the matching the lower-case name, and finally a file matching the mixed-case name. All macro files placed in the ``apdl`` directory must be upper-case. - - Because undocumented commands exist in Mechanical APDL, you should issue the command intended for the macro file name to ensure that the unknown-command message is output in the processor where it is to be used. If the macro is to be used in other processors, the other processors must also be checked. - - This command is valid in any processor. + Removes a directory on the computer on which Mechanical APDL is currently running. No warning or prompt is + given, so use with extreme caution. """ - command = f"*USE,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{ar10},{ar11},{ar12},{ar13},{ar14},{ag15},{ar16},{ar17},{ar18}" + command = f"/RMDIR" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py b/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py index dcb0873312..840dac5aee 100644 --- a/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py +++ b/src/ansys/mapdl/core/_commands/apdl/matrix_operations.py @@ -23,494 +23,470 @@ class MatrixOperations: - def axpy(self, vr="", vi="", m1="", wr="", wi="", m2="", **kwargs): - r"""Performs the matrix operation M2= v\*M1 + w\*M2. + def starprint(self, matrix: str = "", fname: str = "", **kwargs): + r"""Prints the matrix values to a file. - Mechanical APDL Command: `\*AXPY `_ + Mechanical APDL Command: `\*PRINT `_ Parameters ---------- - vr, vi : str - The real and imaginary parts of the scalar ``v`` . Default value is 0. - - m1 : str - Name of matrix ``M1`` . If not specified, the operation M2 = w\*M2 will be performed. - - wr, wi : str - The real and imaginary parts of the scalar ``w`` . Default value is 0. + matrix : str + Name of matrix or vector to print. Must be specified. - m2 : str - Name of matrix ``M2`` . Must be specified. + fname : str + File name (case-sensitive, 32-character maximum). If blank, matrix is written to the output + file. Notes ----- - The matrices ``M1`` and ``M2`` must have the same dimensions and same type (dense or sparse). If ``M2`` is real, ``vi`` and ``wi`` are ignored. + The matrix may be a dense matrix ( :ref:`dmat` ), a sparse matrix ( :ref:`smat` ), or a vector ( + :ref:`vec` ). Only the non-zero entries of the matrix are printed. """ - command = f"*AXPY,{vr},{vi},{m1},{wr},{wi},{m2}" + command = f"*PRINT,{matrix},{fname}" return self.run(command, **kwargs) - def comp(self, matrix="", algorithm="", threshold="", val1="", val2="", **kwargs): - r"""Compresses a matrix using a specified algorithm. + def free(self, name: str = "", val1: str = "", **kwargs): + r"""Deletes a matrix or a solver object and frees its memory allocation. - Mechanical APDL Command: `\*COMP `_ + Mechanical APDL Command: `\*FREE `_ Parameters ---------- - matrix : str - Name of the matrix to compress. - - algorithm : str - Algorithm or method to use: - - * ``SVD`` - Singular value decomposition algorithm (default). - - * ``MGS`` - Modified Gram-Schmidt algorithm. - - * ``SPARSE`` - Compress a sparse matrix based on the threshold value. - - threshold : str - Numerical threshold value used to manage the compression. The default value depends on the - method of compression: 1E-7 for SVD; 1E-14 for MGS; 1E-16 for SPARSE. - - ``Val1`` and ``Val2`` are additional input used only for the SVD algorithm: + name : str + Name of the matrix or solver object to delete. Use ``Name`` = ALL to delete all APDL Math + matrices and solver objects. Use ``Name`` = WRK to delete all APDL Math matrices and solver + objects that belong to a given workspace. val1 : str - Name of the vector used to store the :math:`` values (see below). This argument is optional. - - val2 : str - Name of the dense matrix used to store the :math:`` output matrix (see below). This argument - is optional. + If ``Name`` = WRK, ``Val1`` is the memory workspace number. Notes ----- - The SVD and MGS algorithms are only applicable to dense matrices that were created using the :ref:`dmat` command. Columns that are linearly dependent on others are removed, leaving the independent or basis vectors. The matrix is resized according to the new size determined by the algorithm. - - For the SVD algorithm, the singular value decomposition of an input matrix :math:`` is a factorization of the form: - - .. math:: - - Here, the :math:`` matrix is replaced by the :math:`` matrix, according to the specified threshold. - - The SPARSE compression method is only applicable to sparse matrices that were created using the :ref:`smat` command. All terms that have an absolute value below the specified threshold, relative to the maximum value in the matrix, are removed from the original matrix. For example, given a sparse matrix having 100 as the largest term and ``THRESHOLD`` = 0.5, all terms having an absolute value below 0.5\*100 = 50 are removed. + A :ref:`clear` command will automatically delete all the current APDL Math objects. """ - command = f"*COMP,{matrix},{algorithm},{threshold},{val1},{val2}" + command = f"*FREE,{name},{val1}" return self.run(command, **kwargs) - def dmat( + def fft( self, - matrix="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", - val5="", + type_: str = "", + inputdata: str = "", + outputdata: str = "", + dim1: str = "", + dim2: str = "", + resultformat: str = "", **kwargs, ): - r"""Creates a dense matrix. + r"""Computes the fast Fourier transformation of a specified matrix or vector. - Mechanical APDL Command: `\*DMAT `_ + Mechanical APDL Command: `\*FFT `_ Parameters ---------- - matrix : str - Name used to identify the matrix. Must be specified. - type : str - Matrix type: - - * ``D`` - Double precision real values (default). - - * ``Z`` - Complex double precision values. - - * ``I`` - Integer values. + Type of FFT transformation: - method : str - Method used to create the matrix: + * ``FORW`` - Forward FFT computation (default). + * ``BACK`` - Backward FFT computation. - * ``ALLOC`` - Allocate space for a matrix (default). + inputdata : str + Name of matrix or vector for which the FFT will be computed. This can be a dense matrix (created + by the :ref:`dmat` command) or a vector (created by the :ref:`vec` command). Data can be real or + complex values. There is no default value for this argument. - * ``RESIZE`` - Resize an existing matrix to new row and column dimensions. Values are kept - from - the original matrix. If the dimensions specified by ``Val1`` (rows) and ``Val2`` (columns) are + outputdata : str + Name of matrix or vector where the FFT results will be stored. The type of this argument must be + consistent with ``InputData`` (see table below). There is no default value for this argument. + InformalTables need to be added. - greater than the original matrix size, the additional entries are assigned a value of zero. + dim1 : str + The number of terms to consider for a vector, or the number of rows for a matrix. Defaults to + the whole input vector or all the rows of the matrix. - * ``COPY`` - Copy an existing matrix. + dim2 : str + The number of columns to consider for a matrix. Defaults to all the columns of the matrix. + (Valid only for matrices.) - * ``LINK`` - Link to an existing matrix. The memory will be shared between the original - matrix - and the new matrix. This is useful for manipulating a submatrix of a larger matrix. The - ``Val1`` - through ``Val5`` arguments will be used to specify the lower and upper bounds of row and - column - numbers from the original matrix. + resultformat : str + Specifies the result format: - * ``IMPORT`` - Import the matrix from a file. + * ``FULL`` - Returns the full result. That is, the result matches the dimension specified on this + command ( ``DIM1``, ``DIM2`` ). + * ``PART`` - Returns partial results. For real input data, there is a symmetry in the results of the + Fourier transform as some coefficients are conjugated. The partial format uses this symmetry to + optimize the storage of the results. (Valid only for real data.) - val1, val2, val3, val4, val5 : str - Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified - ``Method`` . See details below. + Notes + ----- + In the example that follows, the fast Fourier transformation is used to filter frequencies from a + noisy input signal. + """ + command = f"*FFT,{type_},{inputdata},{outputdata},{dim1},{dim2},{resultformat}" + return self.run(command, **kwargs) - The following ``Valx`` fields are used with ``Method`` = ALLOC or ``Method`` = RESIZE: + def wrk(self, num: str = "", **kwargs): + r"""Sets the active workspace number. - val1 : str - Number of rows in the matrix. + Mechanical APDL Command: `\*WRK `_ - val2 : str - Number of columns in the matrix. + Parameters + ---------- + num : str + Number of the active memory workspace for APDLMath vector and matrices. All the following + APDLMath vectors and matrices will belong to this memory workspace, until the next call to the + :ref:`wrk` command. By default, all the APDLMath objects belong to workspace number 1. - val3 : str - Memory allocation type (used only with ``Method`` = ALLOC): + Notes + ----- + This feature enables you to associate a set of vector and matrices in a given memory workspace, so + that you can easily manage the free step: - * ``INCORE`` - In-core memory allocation (default). + .. code:: - * ``OUTOFCORE`` - Out-of-core memory allocation. + \*VEC,V,D,ALLOC,5 ! V belongs to the default Workspace 1 - The following ``Valx`` fields are used with ``Method`` = COPY: + \*WRK,2 ! Set the active workspace as the number 2 - val1 : str - Name of the matrix to copy. + \*VEC,W,D,IMPORT,FULL,file.full,RHS ! W belongs to the Workspace 2 + \*SMAT,K,D,IMPORT,FULL,file.full,STIFF ! K belongs to the Workspace 2 + \*DMAT,M,ALLOC,10,10 ! M belongs to the Workspace 2 + … + \*FREE,WRK,2 ! W, K and M are deleted, but not V - val2 : str - Method used for copying the matrix: + \*PRINT,V - * ``TRANS`` - Transpose the original matrix. ``Val3`` and ``Val4`` are ignored. + This feature can be useful to free all the temporary APDLMath variables inside a MACRO in one call. + """ + command = f"*WRK,{num}" + return self.run(command, **kwargs) - * ``REAL`` - Copy the real part to the output matrix. This option only applies when copying - a - complex value matrix to a real value matrix. ``Val3`` and ``Val4`` are ignored. + def comp( + self, + matrix: str = "", + algorithm: str = "", + threshold: str = "", + val1: str = "", + val2: str = "", + **kwargs, + ): + r"""Compresses a matrix using a specified algorithm. - * ``IMAG`` - Copy the imaginary part to the output matrix. This option only applies when - copying - a complex value matrix to a real value matrix. ``Val3`` and ``Val4`` are ignored. + Mechanical APDL Command: `\*COMP `_ - * ``EXTRACT`` - Extract a submatrix based on row and column numbers specified by ``Val3`` - and - ``Val4`` . + Parameters + ---------- + matrix : str + Name of the matrix to compress. - val3 : str - Name of integer vector ( :ref:`vec` ) containing row numbers. If no vector is specified, - defaults to all rows. + algorithm : str + Algorithm or method to use: - val4 : str - Name of integer vector ( :ref:`vec` ) containing column numbers. If no vector is specified, - defaults to all columns. + * ``SVD`` - Singular value decomposition algorithm (default). + * ``MGS`` - Modified Gram-Schmidt algorithm. + * ``SPARSE`` - Compress a sparse matrix based on the threshold value. - The following ``Valx`` fields are used with ``Method`` = LINK: + threshold : str + Numerical threshold value used to manage the compression. The default value depends on the + method of compression: 1E-7 for SVD; 1E-14 for MGS; 1E-16 for SPARSE. val1 : str - Name of the original matrix. + Name of the vector used to store the :math:`` values (see below). This argument is optional. val2 : str - First column number (defaults to 1). - - val3 : str - Last column number (defaults to the maximum column number of the original matrix). - - val4 : str - First row number (defaults to 1). - - val5 : str - Last row number (defaults to the maximum row number of the original matrix). - - The following table describes the ``Valx`` fields used with ``Method`` = IMPORT: - - InformalTables need to be added. + Name of the dense matrix used to store the :math:`` output matrix (see below). This argument + is optional. Notes ----- - This command allows you to create a dense matrix. To create a sparse matrix, use the :ref:`smat` command. :ref:`smat` is recommended for large matrices obtained from the ``.FULL`` or ``.HBMAT`` file. Refer to the :ref:`hbmat` command documentation for more information about ``.FULL`` file contents. - - Use the :ref:`vec` command to create a vector. - - For very large matrices, use the OUTOFCORE option ( ``Method`` = ALLOC or COPY) to keep some of the matrix on disk if there is insufficient memory. - - When importing a dense matrix from a DMIG file, you can define the formatting of the file using the ``Val3`` and ``Val4`` fields. Here are a few different example of formats: - - A LARGE field format file (using ``Val3`` = ’LARGE’): - - .. code:: - - ... - DMIG\* KAAX 21 2 - * 21 1-2.261491337E+08 - ... + The SVD and MGS algorithms are only applicable to dense matrices that were created using the + :ref:`dmat` command. Columns that are linearly dependent on others are removed, leaving the + independent or basis vectors. The matrix is resized according to the new size determined by the + algorithm. For the SVD algorithm, the singular value decomposition of an input matrix :math:`` is + a factorization of the form: .. math:: Here, the :math:`` matrix is replaced by the + :math:`` matrix, according to the specified threshold. The SPARSE compression method is only + applicable to sparse matrices that were created using the :ref:`smat` command. All terms that have + an absolute value below the specified threshold, relative to the maximum value in the matrix, are + removed from the original matrix. For example, given a sparse matrix having 100 as the largest term + and ``THRESHOLD`` = 0.5, all terms having an absolute value below 0.5\*100 = 50 are removed. + """ + command = f"*COMP,{matrix},{algorithm},{threshold},{val1},{val2}" + return self.run(command, **kwargs) - A FREE field format file with blank separators (using ``Val4`` = ’S’): + def xpl(self, action: str = "", val1: str = "", val2: str = "", **kwargs): + r"""Accesses content of a Mechanical APDL file. - .. code:: + Mechanical APDL Command: `\*XPL `_ - ... - DMIG stiff 1 2 1 2 29988. - 1 6 149940. 2 2 -29988. - 2 6 149940. - ... + Parameters + ---------- + action : str + Specifies the action for scanning file content (no default). Valid labels are: - A FREE field format file with a comma separator (using ``Val4`` = ’,’): + * ``OPEN`` - Open the specified file. + * ``CLOSE`` - Close the specified file. + * ``LIST`` - List the records at the current level in the hierarchy of records. + * ``WHERE`` - Display the current location in the tree. + * ``STEP`` - Step down in the tree of records. + * ``UP`` - Go up in the tree of records. + * ``READ`` - Read a record into an APDL Math object. + * ``INFO`` - Display information from a record. + * ``GOTO`` - Move directly to a given place in the tree of records (this avoids multiple calls to + the STEP and UP options). + * ``MARK`` - Mark a set of records of the current file; the asterisk (\*) character can be used to + specify multiple branches/records. + * ``COPY`` - Copy the current file to a new one, ignoring the marked records. + * ``SAVE`` - Save the current file, ignoring the marked records. - .. code:: + val1 : str + Additional input. The meanings of ``Val1`` and ``Val2`` vary depending on the specified + ``Action``, as described in the table below. - ... - DMIG,KF,22321,3,,22321,2,-5.00E+6 - DMIG,KF,22320,3,,22320,2,-5.00E+6 - ... + val2 : str + Additional input. The meanings of ``Val1`` and ``Val2`` vary depending on the specified + ``Action``, as described in the table below. - Requirement when importing matrices from a Nastran DMIG file: To ensure that the ``.sub`` file is properly generated from matrices imported from Nastran DMIG file, the generalized coordinates for a CMS superelement (SPOINTS in Nastran) must appear last (have highest ID number). + Notes + ----- + The :ref:`xpl` command enables you to explore the contents of a Mechanical APDL file. Use this command to + traverse up and down the tree structure of the specified file and review what is in the file. Files + that can be scanned include ``.RST``, ``.MODE``, ``.FULL``, ``.CMS``, and ``.SUB`` files. For + more information and examples, see `Using APDL to List File Structure and Content + `_ The command + :ref:`xpl` ,READ generates either a :ref:`vec` or a :ref:`dmat` object according to the record type. + You do not have to create the APDL Math object before issuing this command. This command is valid + in any processor. """ - command = f"*DMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" + command = f"*XPL,{action},{val1},{val2}" return self.run(command, **kwargs) - def dot(self, vector1="", vector2="", par_real="", par_imag="", conj="", **kwargs): - r"""Computes the dot (or inner) product of two vectors. + def nrm( + self, + name: str = "", + normtype: str = "", + parr: str = "", + normalize: str = "", + **kwargs, + ): + r"""Computes the norm of the specified matrix or vector. - Mechanical APDL Command: `\*DOT `_ + Mechanical APDL Command: `\*NRM `_ Parameters ---------- - vector1 : str - Name of first vector; must have been previously specified by a :ref:`vec` command. - - vector2 : str - Name of second vector; must have been previously specified by a :ref:`vec` command. + name : str + Matrix or vector for which the norm will be computed. This can be a dense matrix (created by the + :ref:`dmat` command), a sparse matrix (created by the :ref:`smat` command) or a vector (created + by the :ref:`vec` command) - par_real : str - Parameter name that contains the result. + normtype : str + Mathematical norm to use: - par_imag : str - Parameter name that contains the imaginary part of the result (used only for complex vectors). + * ``NRM2`` - L2 (Euclidian or SRSS) norm (default). + * ``NRM1`` - L1 (absolute sum) norm (vectors and dense matrices only). + * ``NRMINF`` - Maximum norm. - conj : str - Key to specify use of the conjugate of ``Vector1`` when the vectors are complex: + parr : str + Parameter name that contains the result. - * ``TRUE`` - Use the conjugate of ``Vector1`` (default). + normalize : str + Normalization key; to be used only for vectors created by :ref:`vec` : - * ``FALSE`` - Do not use the conjugate of ``Vector1`` . + * ``YES`` - Normalize the vector such that the norm is 1.0. + * ``NO`` - Do not normalize the vector (default). Notes ----- - If ``Vector1`` and ``Vector2`` are complex, the complex conjugate of ``Vector1`` is used to compute the result ( ``Par_Real``, ``Par_Imag`` ). Therefore, \*DOT applied to complex vectors performs the operation: - - .. math:: - - Set ``Conj`` = FALSE if you do not want to use the conjugate of ``Vector1`` . In this case, the operation is: - - .. math:: - - + The NRM2 option corresponds to the Euclidian or L2 norm and is applicable to either vectors or + matrices: :math:``, :math:`` :math:``, :math:`` where :math:`` is the complex conjugate of + :math:`` :math:``, :math:`` = largest eigenvalue of :math:`` The NRM1 option corresponds to + the L1 norm and is applicable to vectors and dense matrices: :math:`` or :math:``, :math:`` + :math:`` or :math:``, :math:`` The NRMINF option is the maximum norm and is applicable to + either vectors or matrices: :math:`` or :math:``, :math:`` :math:`` or :math:``, :math:`` """ - command = f"*DOT,{vector1},{vector2},{par_real},{par_imag},{conj}" + command = f"*NRM,{name},{normtype},{parr},{normalize}" return self.run(command, **kwargs) - def eigen(self, kmatrix="", mmatrix="", cmatrix="", evals="", evects="", **kwargs): - r"""Performs a modal solution with unsymmetric or damping matrices. + def merge( + self, name1: str = "", name2: str = "", val1: str = "", val2: str = "", **kwargs + ): + r"""Merges two dense matrices or vectors into one. - Mechanical APDL Command: `\*EIGEN `_ + Mechanical APDL Command: `\*MERGE `_ Parameters ---------- - kmatrix : str - Name of the stiffness matrix. May be a real or complex-valued matrix. - - mmatrix : str - Name of the mass matrix. + name1 : str + Name of the matrix or vector to extend. - cmatrix : str - Name of the damping matrix (used only for :ref:`modopt` ,DAMP). + name2 : str + Name of the matrix or vector to be merged into ``Name1``. - evals : str - Name of the output eigenvalues vector. It will be an ``m`` -long :ref:`vec` vector of complex - values, where ``m`` is the number of eigenvalues requested ( :ref:`modopt` ). + val1 : str + Additional input. The meaning of ``Val1`` and ``Val2`` varies depending on the entity type + (matrix or vector). See details below. - evects : str - Name of the output eigenvector matrix. It will be a ``n`` x ``m`` :ref:`dmat` (dense) matrix of - complex values, where ``n`` is the size of the matrix and ``m`` is the number of eigenvalues - requested ( :ref:`modopt` ). + val2 : str + Additional input. The meaning of ``Val1`` and ``Val2`` varies depending on the entity type + (matrix or vector). See details below. Notes ----- - Use the command :ref:`antype` ,MODAL and the :ref:`modopt` command to specify the modal solution options. Only :ref:`modopt` ,DAMP, :ref:`modopt` ,UNSYM, :ref:`modopt` ,LANB, and :ref:`modopt` ,SUBSP are supported. - - :ref:`eigen` with Block Lanczos (LANB) only supports sparse matrices. Distributed-Memory Parallel (DMP) Restriction This command is not supported in a DMP solution. + :ref:`merge` can be used to add new columns or rows to a dense matrix that was created by the + :ref:`dmat` command. In this case, ``Name1`` must be the name of the dense matrix and ``Name2`` must + refer to a vector or another dense matrix. The following two examples demonstrate merging columns + into a dense matrix. .. figure::../../images/gMERGE1.png The following example demonstrates + merging rows into a dense matrix. .. figure::../../images/gMERGE3.png :ref:`merge` can also be + used to add new rows to a vector that was created by the :ref:`vec` command. In this case, ``Name1`` + and ``Name2`` must both refer to vectors, as demonstrated in the example below. .. + figure::../../images/gMERGE2.png In all cases, the values of the original matrix or vector are + retained, and the matrix or vector is resized to accommodate the additional rows or columns. """ - command = f"*EIGEN,{kmatrix},{mmatrix},{cmatrix},{evals},{evects}" + command = f"*MERGE,{name1},{name2},{val1},{val2}" return self.run(command, **kwargs) - def export( - self, matrix="", format="", fname="", val1="", val2="", val3="", **kwargs + def mult( + self, + m1: str = "", + t1: str = "", + m2: str = "", + t2: str = "", + m3: str = "", + **kwargs, ): - r"""Exports a matrix to a file in the specified format. + r"""Performs the matrix multiplication M3 = M1 :sup:`(T1)` \*M2 :sup:`(T2)` . - Mechanical APDL Command: `\*EXPORT `_ + Mechanical APDL Command: `\*MULT `_ Parameters ---------- - matrix : str - Name of the matrix to export (must be a matrix previously created with :ref:`dmat` or - :ref:`smat`, or a vector previously created with :ref:`vec` ). - - format : str - Format of the output file: - - * ``MMF`` - Export the matrix in the Matrix Market Format. - - * ``SUB`` - Export the matrix in the ``SUB`` file format. + m1 : str + Name of matrix ``M1``. Must have been previously specified by a :ref:`dmat` or :ref:`smat` + command. - * ``HBMAT`` - Export the matrix in the Harwell-Boeing file format. + t1 : str + Transpose key. Set ``T1`` = TRANS to use the non-conjugate transpose of ``M1``. Set ``T1`` = + CTRANS to use the conjugate transpose of ``M1``. CTRANS is only applicable when the ``M1`` + matrix is complex. If blank, transpose will not be used. - * ``MAT`` - Export the matrix in a native format, to be re-imported using the :ref:`dmat` or + m2 : str + Name of matrix ``M2``. Must have been previously specified by a :ref:`dmat` command. - :ref:`smat` command. + t2 : str + Transpose key. Set ``T2`` = TRANS to use the non-conjugate transpose of ``M2``. Set ``T2`` = + CTRANS to use the conjugate transpose of ``M2``. CTRANS is only applicable when the ``M2`` + matrix is complex. If blank, transpose will not be used. - * ``EMAT`` - Export the matrix to an existing ``EMAT`` file. + m3 : str + Name of resulting matrix, ``M3``. Must be specified. - * ``APDL`` - Export the matrix to an APDL array parameter. + Notes + ----- + The matrices must be dimensionally consistent such that the number of columns of ``M1`` (or the + transposed matrix, if requested) is equal to the number of rows of ``M2`` (or the transposed matrix, + if requested). You cannot multiply two sparse matrices with this command (that is, ``M1`` and + ``M2`` cannot both be sparse). The resulting matrix, ``M3``, will always be a dense matrix, no + matter what combination of input matrices is used (dense\*sparse, sparse\*dense, or dense\*dense). + """ + command = f"*MULT,{m1},{t1},{m2},{t2},{m3}" + return self.run(command, **kwargs) - * ``PS`` - Export the matrix profile to a Postscript file. + def starinquire(self, obj: str = "", property: str = "", var1: str = "", **kwargs): + r"""Retrieves properties of an existing APDL Math object. - * ``DMIG`` - Export the matrix in the ``DMIG`` file format. + Mechanical APDL Command: `\*INQUIRE `_ - * ``CSV`` - Export the matrix to an ASCII CSV (comma-separated values) file. + Parameters + ---------- + obj : str + Name of the vector or matrix of interest. - fname : str - Name of the file (case-sensitive, 32-character maximum), or name of the array parameter if - ``Format`` = APDL (no default) . + property : str + Object property to get: - val1, val2, val3 : str - Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified - ``Format`` . See table below for details. + * ``DIM1`` - First dimension of a matrix, or size of a vector. + * ``DIM2`` - Second dimension of a matrix. - InformalTables need to be added. + var1 : str + Name of the resulting parameter that contains the property value. Notes ----- - Only sparse matrices can be exported to Postscript files. This option plots the matrix profile as a series of dots. - - If you want to create a ``.SUB`` file from several matrices, you need to set ``Val3`` = WAIT for all matrices but the last, and ``Val3`` = DONE for the last one. The export will be effective at the last :ref:`export` command. - - To create a ``.SUB`` file or ``.DMIG`` file from scratch, you must supply the row information array. (Specify this array in the ``Val2`` field for ``.SUB`` or in the ``Val1`` field for ``.DMIG`` .) This must be an ``m`` x 2 array, where ``m`` is the size of the matrix. The first column is the node number and the second column is the DOF number corresponding to each row of the matrix. - - When exporting an HBMAT file in ASCII format, you can include the matrix type in the header of the file by specifying the matrix type in the ``Val2`` field. The matrix type is not included in the header if ``Val2`` is empty. If ``Val1`` = BINARY, ``Val2`` is not used. + The following example demonstrates using :ref:`starinquire` to get the number of rows and columns of an existing matrix. - The :ref:`export` command is not applicable to sparse matrices initialized from ``.FULL`` files by means of the NOD2SOLV option on the :ref:`smat` command (that is, :ref:`smat` ,,,IMPORT,FULL,,NOD2SOLV). + .. code:: - The ``.CSV`` file format does not support sparse matrices. + \*SMAT,K,D,IMPORT,FULL,file.full,STIFF ! Import the stiffness matrix from an existing FULL file + \*INQUIRE,K,DIM1,NROW ! Get the first dimension of the stiffness matrix + \*INQUIRE,K,DIM2,NCOL ! Get the second dimension of the stiffness matrix + /COM, K matrix size: %NROW% x %NCOL% """ - command = f"*EXPORT,{matrix},{format},{fname},{val1},{val2},{val3}" + command = f"*INQUIRE,{obj},{property},{var1}" return self.run(command, **kwargs) - def fft( + def itengine( self, - type_="", - inputdata="", - outputdata="", - dim1="", - dim2="", - resultformat="", + type_: str = "", + enginename: str = "", + precondname: str = "", + matrix: str = "", + rhsvector: str = "", + solvector: str = "", + maxiter: str = "", + toler: str = "", **kwargs, ): - r"""Computes the fast Fourier transformation of a specified matrix or vector. + r"""Performs a solution using an iterative solver. - Mechanical APDL Command: `\*FFT `_ + Mechanical APDL Command: `\*ITENGINE `_ Parameters ---------- type : str - Type of FFT transformation: - - * ``FORW`` - Forward FFT computation (default). - - * ``BACK`` - Backward FFT computation. - - inputdata : str - Name of matrix or vector for which the FFT will be computed. This can be a dense matrix (created - by the :ref:`dmat` command) or a vector (created by the :ref:`vec` command). Data can be real - or complex values. There is no default value for this argument. - - outputdata : str - Name of matrix or vector where the FFT results will be stored. The type of this argument must be - consistent with ``InputData`` (see table below). There is no default value for this argument. - - InformalTables need to be added. - dim1 : str - The number of terms to consider for a vector, or the number of rows for a matrix. Defaults to - the whole input vector or all the rows of the matrix. - - dim2 : str - The number of columns to consider for a matrix. Defaults to all the columns of the matrix. - (Valid only for matrices.) - - resultformat : str - Specifies the result format: - - * ``FULL`` - Returns the full result. That is, the result matches the dimension specified on - - this command ( ``DIM1``, ``DIM2`` ). - - * ``PART`` - Returns partial results. For real input data, there is a symmetry in the - results of - the Fourier transform as some coefficients are conjugated. The partial format uses this - symmetry - to optimize the storage of the results. (Valid only for real data.) - - Notes - ----- - In the example that follows, the fast Fourier transformation is used to filter frequencies from a noisy input signal. - """ - command = f"*FFT,{type_},{inputdata},{outputdata},{dim1},{dim2},{resultformat}" - return self.run(command, **kwargs) - - def free(self, name="", val1="", **kwargs): - r"""Deletes a matrix or a solver object and frees its memory allocation. - - Mechanical APDL Command: `\*FREE `_ + Specifies the algorithm to be used: - Parameters - ---------- - name : str - Name of the matrix or solver object to delete. Use ``Name`` = ALL to delete all APDL Math - matrices and solver objects. Use ``Name`` = WRK to delete all APDL Math matrices and solver - objects that belong to a given workspace. + * ``PCG`` - Preconditioned conjugate gradient (default). - val1 : str - If ``Name`` = WRK, ``Val1`` is the memory workspace number. + enginename : str + Name used to identify this iterative solver engine. Must be specified. - Notes - ----- - A :ref:`clear` command will automatically delete all the current APDL Math objects. - """ - command = f"*FREE,{name},{val1}" - return self.run(command, **kwargs) + precondname : str + Linear solver engine name ( :ref:`lsengine` ) identifying the factored matrix to be used as the + preconditioner. - def hprod(self, a="", b="", c="", **kwargs): - r"""Performs a Hadamard vector product (C = A∘B). + matrix : str + Name of the matrix to solve. - Mechanical APDL Command: `\*HPROD `_ + rhsvector : str + Matrix (load vector) name. - Parameters - ---------- - a : str - Name of vector A. Must have been previously created by a :ref:`vec` command. + solvector : str + Solution vector name. If non-zero, it will be taken as the initial vector for the iterative + process. - b : str - Name of vector B. Must have been previously created by a :ref:`vec` command. + maxiter : str + Maximum number of iterations allowed. Default is 2 times the number of rows in the matrix. - c : str - Name of vector C. Must be specified (no default). + toler : str + Convergence tolerance. Default is 1.0E-8. Notes ----- - For two vectors ``A`` and ``B`` of the same dimension ``n``, the Hadamard product (A∘B) is a vector of the same dimension as the operands, with elements given by: - - .. math:: - - This command is limited to vector operands. + This command solves Ax = b using a preconditioned conjugate gradient algorithm. It uses an existing + factored system as the preconditioner. This solution method is useful if an existing matrix has been + solved and minor changes have been made to the matrix. """ - command = f"*HPROD,{a},{b},{c}" + command = f"*ITENGINE,{type_},{enginename},{precondname},{matrix},{rhsvector},{solvector},{maxiter},{toler}" return self.run(command, **kwargs) - def init(self, name="", method="", val1="", val2="", val3="", **kwargs): + def init( + self, + name: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + **kwargs, + ): r"""Initializes a vector or matrix. Mechanical APDL Command: `\*INIT `_ @@ -525,476 +501,554 @@ def init(self, name="", method="", val1="", val2="", val3="", **kwargs): method : str Initialization method to use: - * ``ZERO`` - Fill the vector/matrix with zeros (default). - - * ``CONST`` - Fill the vector/matrix with a constant value. - - * ``RAND`` - Fill the vector/matrix with random values. - - * ``DIAG`` - Fill the ``n`` th diagonal of the matrix with a constant value. Other values - are + * ``ZERO`` - Fill the vector/matrix with zeros (default). + * ``CONST`` - Fill the vector/matrix with a constant value. + * ``RAND`` - Fill the vector/matrix with random values. + * ``DIAG`` - Fill the ``n`` th diagonal of the matrix with a constant value. Other values are not + overwritten. For this option, ``Name`` must be a dense matrix. + * ``ADIAG`` - Fill the ``n`` th anti-diagonal of the matrix with a constant value. Other values are not overwritten. For this option, ``Name`` must be a dense matrix. - - * ``ADIAG`` - Fill the ``n`` th anti-diagonal of the matrix with a constant value. Other - values - are not overwritten. For this option, ``Name`` must be a dense matrix. - - * ``CONJ`` - Take the complex conjugate of the values in the vector/matrix (no change for - non- + * ``CONJ`` - Take the complex conjugate of the values in the vector/matrix (no change for non- complex values). - - * ``FILTER`` - Initialize a subset of values of a vector using a filtering vector. For this - option, ``Name`` must be a vector. - - val1, val2, val3 : str - Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified - ``Method`` . See details below. - - The following ``Valx`` fields are used with ``Method`` = CONST: + * ``FILTER`` - Initialize a subset of values of a vector using a filtering vector. For this option, + ``Name`` must be a vector. val1 : str - The real part of the constant value to use (default = 0). + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. val2 : str - The imaginary part of the constant value to use (default = 0). Required only for a complex - vector/matrix. + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. - The following ``Valx`` fields are used with ``Method`` = DIAG or ``Method`` = ADIAG: + val3 : str + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Method``. See details below. - val1 : str - The number of the diagonal to fill. A zero value (which is the default) indicates the main - diagonal (or main anti-diagonal). A positive value indicates an upper diagonal; a negative value - indicates a lower diagonal. + Notes + ----- + This command initializes a previously defined vector ( :ref:`vec` ), dense matrix ( :ref:`dmat` ), + or sparse matrix ( :ref:`smat` ). + """ + command = f"*INIT,{name},{method},{val1},{val2},{val3}" + return self.run(command, **kwargs) - val2 : str - The real part of the constant value to use (default = 1). + def export( + self, + matrix: str = "", + format: str = "", + fname: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + **kwargs, + ): + r"""Exports a matrix to a file in the specified format. - val3 : str - The imaginary part of the constant value to use (default = 0). Required only for a complex - matrix . + Mechanical APDL Command: `\*EXPORT `_ + + Parameters + ---------- + matrix : str + Name of the matrix to export (must be a matrix previously created with :ref:`dmat` or + :ref:`smat`, or a vector previously created with :ref:`vec` ). - The following example demonstrates ``Method`` = DIAG: + format : str + Format of the output file: - .. figure:: ../../images/gINIT1.svg + * ``MMF`` - Export the matrix in the Matrix Market Format. + * ``SUB`` - Export the matrix in the ``SUB`` file format. + * ``HBMAT`` - Export the matrix in the Harwell-Boeing file format. + * ``MAT`` - Export the matrix in a native format, to be re-imported using the :ref:`dmat` or + :ref:`smat` command. + * ``EMAT`` - Export the matrix to an existing ``EMAT`` file. + * ``APDL`` - Export the matrix to an APDL array parameter. + * ``PS`` - Export the matrix profile to a Postscript file. + * ``DMIG`` - Export the matrix in the ``DMIG`` file format. + * ``CSV`` - Export the matrix to an ASCII CSV (comma-separated values) file. - The following ``Valx`` fields are used with ``Method`` = FILTER: + fname : str + Name of the file (case-sensitive, 32-character maximum), or name of the array parameter if + ``Format`` = APDL (no default). val1 : str - The name of an existing integer vector (created by :ref:`vec` ) to be used as the filter vector. - The values in this vector indicate the locations in the ``Name`` vector that are to be - initialized to ``Val2`` (real value) and ``Val3`` (imaginary value, if applicable). Location - values higher than the dimension of the original vector are ignored. + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. val2 : str - The real part of the value used for initialization (default = 0). + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. val3 : str - The imaginary part of the value used for initialization (default = 0); applicable only if the - ``Name`` vector contains complex values. + Additional input. The meaning of ``Val1`` through ``Val3`` will vary depending on the specified + ``Format``. See table below for details. Notes ----- - This command initializes a previously defined vector ( :ref:`vec` ), dense matrix ( :ref:`dmat` ), or sparse matrix ( :ref:`smat` ). + Only sparse matrices can be exported to Postscript files. This option plots the matrix profile as a + series of dots. If you want to create a ``.SUB`` file from several matrices, you need to set + ``Val3`` = WAIT for all matrices but the last, and ``Val3`` = DONE for the last one. The export will + be effective at the last :ref:`export` command. To create a ``.SUB`` file or ``.DMIG`` file from + scratch, you must supply the row information array. (Specify this array in the ``Val2`` field for + ``.SUB`` or in the ``Val1`` field for ``.DMIG``.) This must be an ``m`` x 2 array, where ``m`` is + the size of the matrix. The first column is the node number and the second column is the DOF number + corresponding to each row of the matrix. When exporting an HBMAT file in ASCII format, you can + include the matrix type in the header of the file by specifying the matrix type in the ``Val2`` + field. The matrix type is not included in the header if ``Val2`` is empty. If ``Val1`` = BINARY, + ``Val2`` is not used. The :ref:`export` command is not applicable to sparse matrices initialized + from ``.FULL`` files by means of the NOD2SOLV option on the :ref:`smat` command (that is, + :ref:`smat` ,,,IMPORT,FULL,,NOD2SOLV). The ``.CSV`` file format does not support sparse matrices. """ - command = f"*INIT,{name},{method},{val1},{val2},{val3}" + command = f"*EXPORT,{matrix},{format},{fname},{val1},{val2},{val3}" return self.run(command, **kwargs) - def starinquire(self, obj="", property="", var1="", **kwargs): - r"""Retrieves properties of an existing APDL Math object. + def eigen( + self, + kmatrix: str = "", + mmatrix: str = "", + cmatrix: str = "", + evals: str = "", + evects: str = "", + **kwargs, + ): + r"""Performs a modal solution with unsymmetric or damping matrices. - Mechanical APDL Command: `\*INQUIRE `_ + Mechanical APDL Command: `\*EIGEN `_ Parameters ---------- - obj : str - Name of the vector or matrix of interest. + kmatrix : str + Name of the stiffness matrix. May be a real or complex-valued matrix. - property : str - Object property to get: + mmatrix : str + Name of the mass matrix. - * ``DIM1`` - First dimension of a matrix, or size of a vector. + cmatrix : str + Name of the damping matrix (used only for :ref:`modopt` ,DAMP). - * ``DIM2`` - Second dimension of a matrix. + evals : str + Name of the output eigenvalues vector. It will be an ``m`` -long :ref:`vec` vector of complex + values, where ``m`` is the number of eigenvalues requested ( :ref:`modopt` ). - var1 : str - Name of the resulting parameter that contains the property value. + evects : str + Name of the output eigenvector matrix. It will be a ``n`` x ``m`` :ref:`dmat` (dense) matrix of + complex values, where ``n`` is the size of the matrix and ``m`` is the number of eigenvalues + requested ( :ref:`modopt` ). Notes ----- - The following example demonstrates using :ref:`starinquire` to get the number of rows and columns of an existing matrix. - - .. code:: - - \*SMAT,K,D,IMPORT,FULL,file.full,STIFF ! Import the stiffness matrix from an existing FULL file - \*INQUIRE,K,DIM1,NROW ! Get the first dimension of the stiffness matrix - \*INQUIRE,K,DIM2,NCOL ! Get the second dimension of the stiffness matrix - /COM, K matrix size: %NROW% x %NCOL% + Use the command :ref:`antype` ,MODAL and the :ref:`modopt` command to specify the modal solution + options. Only :ref:`modopt` ,DAMP, :ref:`modopt` ,UNSYM, :ref:`modopt` ,LANB, and :ref:`modopt` + ,SUBSP are supported. :ref:`eigen` with Block Lanczos (LANB) only supports sparse matrices. + Distributed-Memory Parallel (DMP) Restriction This command is not supported in a DMP solution. """ - command = f"*INQUIRE,{obj},{property},{var1}" + command = f"*EIGEN,{kmatrix},{mmatrix},{cmatrix},{evals},{evects}" return self.run(command, **kwargs) - def itengine( + def smat( self, - type_="", - enginename="", - precondname="", - matrix="", - rhsvector="", - solvector="", - maxiter="", - toler="", + matrix: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", **kwargs, ): - r"""Performs a solution using an iterative solver. + r"""Creates a sparse matrix. - Mechanical APDL Command: `\*ITENGINE `_ + Mechanical APDL Command: `\*SMAT `_ Parameters ---------- + matrix : str + Name used to identify the matrix. Must be specified. + type : str - Specifies the algorithm to be used: + Matrix type: - * ``PCG`` - Preconditioned conjugate gradient (default). + * ``D`` - Double precision real values (default). + * ``Z`` - Complex double precision values. - enginename : str - Name used to identify this iterative solver engine. Must be specified. + method : str + Method used to create the matrix: - precondname : str - Linear solver engine name ( :ref:`lsengine` ) identifying the factored matrix to be used as the - preconditioner. + * ``ALLOC`` - Allocate a new matrix. + * ``COPY`` - Copy an existing matrix. + * ``IMPORT`` - Import the matrix from a file. - matrix : str - Name of the matrix to solve. + val1 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - rhsvector : str - Matrix (load vector) name. + val2 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - solvector : str - Solution vector name. If non-zero, it will be taken as the initial vector for the iterative - process. + val3 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - maxiter : str - Maximum number of iterations allowed. Default is 2 times the number of rows in the matrix. + val4 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - toler : str - Convergence tolerance. Default is 1.0E-8. + val5 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. Notes ----- - This command solves Ax = b using a preconditioned conjugate gradient algorithm. It uses an existing factored system as the preconditioner. This solution method is useful if an existing matrix has been solved and minor changes have been made to the matrix. + Use the :ref:`dmat` command to create a dense matrix. For more information on the CSR format, see + `Creating a Sparse Matrix Using the CSR Format + `_ For more information on the NOD2SOLV and USR2SOLV mapping vectors, see. For more + information about ``.FULL`` file contents, see the :ref:`hbmat` in the `Command Reference `_. """ - command = f"*ITENGINE,{type_},{enginename},{precondname},{matrix},{rhsvector},{solvector},{maxiter},{toler}" + command = f"*SMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" return self.run(command, **kwargs) - def lsbac(self, enginename="", rhsvector="", solvector="", transkey="", **kwargs): - r"""Performs the solve (forward/backward substitution) of a factorized linear system. + def starsort( + self, + name: str = "", + sorttype: str = "", + val1: str = "", + val2: str = "", + **kwargs, + ): + r"""Sorts the values of the specified vector. - Mechanical APDL Command: `\*LSBAC `_ + Mechanical APDL Command: `\*SORT `_ Parameters ---------- - enginename : str - Name used to identify this engine. Must have been previously created using :ref:`lsengine` and - factorized using :ref:`lsfactor` . + name : str + Name of the vector to be sorted. This vector can contain real or complex values. - rhsvector : str - Name of vector containing the right-hand side (load) vectors as input. Must have been previously - defined as a :ref:`vec` vector or a :ref:`dmat` matrix. + sorttype : str + Criteria used to sort the values: - solvector : str - Name of vector that will contain the solution vectors upon completion. Must be predefined as a - :ref:`vec` vector or :ref:`dmat` matrix. + * ``VALUE`` - Values are sorted based on their real value (default). + * ``ABS`` - Values are sorted based on their absolute value. + * ``PERM`` - Values are sorted based on the input permutation vector ( ``Val1`` ). - transkey : str - Transpose key. Set ``TransKey`` = TRANS to solve the transposed linear system. If blank, - transpose will not be used. + val1 : str + Additional input. The meaning of ``Val1``, ``Val2`` varies depending on the specified + ``SortType``. See below for details. + + val2 : str + Additional input. The meaning of ``Val1``, ``Val2`` varies depending on the specified + ``SortType``. See below for details. Notes ----- - This command performs forward and back substitution to obtain the solution to the linear matrix equation Ax = b (or A :sup:`T` x = b if ``TransKey`` = TRANS). The matrix engine must have been previously defined using :ref:`lsengine`, and the matrix factored using :ref:`lsfactor` . + The examples below demonstrate using :ref:`starsort` to sort the values of an input vector. + + The following input: + + .. code:: + + \*VEC,V,I,ALLOC,5 + V(1)=5,-3,2,0,-1 + \*SORT,V,VALUE + \*PRINT,V + + generates this output: + + .. code:: + + -3 -1 0 2 5 + + To reverse the order, this input: + + .. code:: + + \*SORT,V,VALUE,,1 + \*PRINT,V + + generates this output: - You can use the :ref:`dmat` ,,,COPY (or :ref:`vec` ,,,COPY) command to copy the load vector to the solution vector in order to predefine it with the appropriate size. + .. code:: + + 5 2 0 -1 -3 """ - command = f"*LSBAC,{enginename},{rhsvector},{solvector},{transkey}" + command = f"*SORT,{name},{sorttype},{val1},{val2}" return self.run(command, **kwargs) - def lsdump(self, enginename="", filename="", **kwargs): - r"""Dumps a linear solver engine to a binary File. + def scal(self, name: str = "", val1: str = "", val2: str = "", **kwargs): + r"""Scales a vector or matrix by a constant. - Mechanical APDL Command: `\*LSDUMP `_ + Mechanical APDL Command: `\*SCAL `_ Parameters ---------- - enginename : str - Name used to identify this engine. Must have been previously created using :ref:`lsengine` and - factorized using :ref:`lsfactor` . + name : str + Name used to identify the vector or matrix to be scaled. Must be specified. - filename : str - Name of the file to create. + val1 : str + The real part of the constant to use (default = 1). + + val2 : str + The imaginary part of the constant to use (default = 0). This value is used only if the vector + or matrix specified by ``Name`` is complex. Notes ----- - Dumps a previously factorized linear solver system to a binary file. Only LAPACK and BCS linear solvers can be used with this feature. The Linear Solver can later be restored with the :ref:`lsrestore` command. - - A BCS Sparse Solver can be dumped only if uses the ``INCORE`` memory option (see :ref:`bcsoption` ). - - Caret 7? + This command can be applied to vectors and matrices created by the :ref:`vec`, :ref:`dmat` and + :ref:`smat` commands. """ - command = f"*LSDUMP,{enginename},{filename}" + command = f"*SCAL,{name},{val1},{val2}" return self.run(command, **kwargs) - def lsengine(self, type_="", enginename="", matrix="", option="", **kwargs): - r"""Creates a linear solver engine. + def vec( + self, + vector: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + **kwargs, + ): + r"""Creates a vector. - Mechanical APDL Command: `\*LSENGINE `_ + Mechanical APDL Command: `\*VEC `_ Parameters ---------- + vector : str + Name used to identify the vector. Must be specified. + type : str - Specifies the algorithm to be used: + Vector type: - * ``DSS`` - MKL sparse linear solver. + * ``D`` - Double precision real values (default). + * ``Z`` - Complex double precision values. + * ``I`` - Integer values. - * ``LAPACK`` - LAPACK dense matrix linear solver (default if applied to dense matrices). + method : str + Method used to create the vector: - * ``DSP`` - Distributed sparse solver (default for sparse matrices). + * ``ALLOC`` - Allocate space for a vector (default). + * ``RESIZE`` - Resize an existing vector to a new length. Values are kept from the original vector. + If the length specified by ``Val1`` is greater than the original vector length, the additional + rows are assigned a value of zero. + * ``COPY`` - Copy an existing vector. + * ``IMPORT`` - Import the vector from a file. + * ``LINK`` - Link to a column of an existing dense :ref:`dmat` matrix and use it in subsequent + vector calculations. Any changes to the vector are also made to the corresponding matrix column + (memory is shared). - enginename : str - Name used to identify this engine. Must be specified. + val1 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - matrix : str - Name of the matrix to solve. + val2 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - option : str - Option to control the memory mode of the DSS solver (used only if ``Type`` = DSS): + val3 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - * ``INCORE`` - In-core memory mode. + val4 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - * ``OUTOFCORE`` - Out-of-core memory mode. + val5 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. Notes ----- - This command creates a linear solver engine. - - The DSS and DSP solvers can only be used with sparse matrices. For dense matrices, use the LAPACK solver. + Use the :ref:`dmat` command to create a matrix. For more information on the BACK and FORWARD nodal + mapping vectors, see in the `Ansys Parametric Design Language Guide `_. """ - command = f"*LSENGINE,{type_},{enginename},{matrix},{option}" + command = f"*VEC,{vector},{type_},{method},{val1},{val2},{val3},{val4},{val5}" return self.run(command, **kwargs) - def lsfactor(self, enginename="", option="", **kwargs): - r"""Performs the numerical factorization of a linear solver system. + def hprod(self, a: str = "", b: str = "", c: str = "", **kwargs): + r"""Performs a Hadamard vector product (C = A∘B). - Mechanical APDL Command: `\*LSFACTOR `_ + Mechanical APDL Command: `\*HPROD `_ Parameters ---------- - enginename : str - Name used to identify this engine. Must have been previously created using :ref:`lsengine` . + a : str + Name of vector A. Must have been previously created by a :ref:`vec` command. - option : str - Option to invert the matrix, used only with an LAPACK engine ( :ref:`lsengine` ,LAPACK): + b : str + Name of vector B. Must have been previously created by a :ref:`vec` command. - * ``INVERT`` - Invert the matrix. + c : str + Name of vector C. Must be specified (no default). Notes ----- - Performs the computationally intensive, memory intensive factorization of a matrix specified by :ref:`lsengine`, using the solver engine also specified by :ref:`lsengine` . + For two vectors ``A`` and ``B`` of the same dimension ``n``, the Hadamard product (A∘B) is a vector + of the same dimension as the operands, with elements given by: .. math:: This command is + limited to vector operands. """ - command = f"*LSFACTOR,{enginename},{option}" + command = f"*HPROD,{a},{b},{c}" return self.run(command, **kwargs) - def lsrestore(self, enginename="", filename="", **kwargs): - r"""Restores a linear solver engine from a binary file. + def lsengine( + self, + type_: str = "", + enginename: str = "", + matrix: str = "", + option: str = "", + **kwargs, + ): + r"""Creates a linear solver engine. - Mechanical APDL Command: `\*LSRESTORE `_ + Mechanical APDL Command: `\*LSENGINE `_ Parameters ---------- + type : str + Specifies the algorithm to be used: + + * ``DSS`` - MKL sparse linear solver. + * ``LAPACK`` - LAPACK dense matrix linear solver (default if applied to dense matrices). + * ``DSP`` - Distributed sparse solver (default for sparse matrices). + enginename : str - Name used to identify this engine. + Name used to identify this engine. Must be specified. - filename : str - Name of the file to read from. + matrix : str + Name of the matrix to solve. + + option : str + Option to control the memory mode of the DSS solver (used only if ``Type`` = DSS): + + * ``INCORE`` - In-core memory mode. + * ``OUTOFCORE`` - Out-of-core memory mode. Notes ----- - Restores a previously dumped Linear Solver (see the :ref:`lsdump` command). This Linear Solver can be used to solve a linear system using the :ref:`lsbac` command. - - Caret 122? + This command creates a linear solver engine. The DSS and DSP solvers can only be used with sparse + matrices. For dense matrices, use the LAPACK solver. """ - command = f"*LSRESTORE,{enginename},{filename}" + command = f"*LSENGINE,{type_},{enginename},{matrix},{option}" return self.run(command, **kwargs) - def merge(self, name1="", name2="", val1="", val2="", **kwargs): - r"""Merges two dense matrices or vectors into one. + def lsfactor(self, enginename: str = "", option: str = "", **kwargs): + r"""Performs the numerical factorization of a linear solver system. - Mechanical APDL Command: `\*MERGE `_ + Mechanical APDL Command: `\*LSFACTOR `_ Parameters ---------- - name1 : str - Name of the matrix or vector to extend. - - name2 : str - Name of the matrix or vector to be merged into ``Name1`` . - - val1, val2 : str - Additional input. The meaning of ``Val1`` and ``Val2`` varies depending on the entity type - (matrix or vector). See details below. - - The following ``Val1`` and ``Val2`` fields are used if ``Name1`` refers to a dense matrix created by the :ref:`dmat` command: - - val1 : str - Column or row number indicating where the new values are to be inserted into the ``Name1`` - matrix. - - val2 : str - Specifies how the ``Name2`` matrix or vector is copied into the ``Name1`` matrix. - - * ``COL`` - Insert the new values at the column location specified by ``Val1`` (default). - - * ``ROW`` - Insert the new values at the row location specified by ``Val1`` . + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine`. - The following ``Val1`` field is used if ``Name1`` refers to a vector created by the :ref:`vec` command: + option : str + Option to invert the matrix, used only with an LAPACK engine ( :ref:`lsengine` ,LAPACK): - val1 : str - Row number indicating where the new values are to be inserted into the ``Name1`` vector. + * ``INVERT`` - Invert the matrix. Notes ----- - :ref:`merge` can be used to add new columns or rows to a dense matrix that was created by the :ref:`dmat` command. In this case, ``Name1`` must be the name of the dense matrix and ``Name2`` must refer to a vector or another dense matrix. - - The following two examples demonstrate merging columns into a dense matrix. - - .. figure:: ../../images/gMERGE1.png - - The following example demonstrates merging rows into a dense matrix. - - .. figure:: ../../images/gMERGE3.png - - :ref:`merge` can also be used to add new rows to a vector that was created by the :ref:`vec` command. In this case, ``Name1`` and ``Name2`` must both refer to vectors, as demonstrated in the example below. - - .. figure:: ../../images/gMERGE2.png - - In all cases, the values of the original matrix or vector are retained, and the matrix or vector is resized to accommodate the additional rows or columns. + Performs the computationally intensive, memory intensive factorization of a matrix specified by + :ref:`lsengine`, using the solver engine also specified by :ref:`lsengine`. """ - command = f"*MERGE,{name1},{name2},{val1},{val2}" + command = f"*LSFACTOR,{enginename},{option}" return self.run(command, **kwargs) - def mult(self, m1="", t1="", m2="", t2="", m3="", **kwargs): - r"""Performs the matrix multiplication M3 = M1 :sup:`(T1)` \*M2 :sup:`(T2)` . + def lsrestore(self, enginename: str = "", filename: str = "", **kwargs): + r"""Restores a linear solver engine from a binary file. - Mechanical APDL Command: `\*MULT `_ + Mechanical APDL Command: `\*LSRESTORE `_ Parameters ---------- - m1 : str - Name of matrix ``M1`` . Must have been previously specified by a :ref:`dmat` or :ref:`smat` - command. - - t1 : str - Transpose key. Set ``T1`` = TRANS to use the non-conjugate transpose of ``M1`` . Set ``T1`` = - CTRANS to use the conjugate transpose of ``M1`` . CTRANS is only applicable when the ``M1`` - matrix is complex. If blank, transpose will not be used. - - m2 : str - Name of matrix ``M2`` . Must have been previously specified by a :ref:`dmat` command. - - t2 : str - Transpose key. Set ``T2`` = TRANS to use the non-conjugate transpose of ``M2`` . Set ``T2`` = - CTRANS to use the conjugate transpose of ``M2`` . CTRANS is only applicable when the ``M2`` - matrix is complex. If blank, transpose will not be used. + enginename : str + Name used to identify this engine. - m3 : str - Name of resulting matrix, ``M3`` . Must be specified. + filename : str + Name of the file to read from. Notes ----- - The matrices must be dimensionally consistent such that the number of columns of ``M1`` (or the transposed matrix, if requested) is equal to the number of rows of ``M2`` (or the transposed matrix, if requested). - - You cannot multiply two sparse matrices with this command (that is, ``M1`` and ``M2`` cannot both be sparse). The resulting matrix, ``M3``, will always be a dense matrix, no matter what combination of input matrices is used (dense\*sparse, sparse\*dense, or dense\*dense). + Restores a previously dumped Linear Solver (see the :ref:`lsdump` command). This Linear Solver can + be used to solve a linear system using the :ref:`lsbac` command. Caret 122? """ - command = f"*MULT,{m1},{t1},{m2},{t2},{m3}" + command = f"*LSRESTORE,{enginename},{filename}" return self.run(command, **kwargs) - def nrm(self, name="", normtype="", parr="", normalize="", **kwargs): - r"""Computes the norm of the specified matrix or vector. + def lsbac( + self, + enginename: str = "", + rhsvector: str = "", + solvector: str = "", + transkey: str = "", + **kwargs, + ): + r"""Performs the solve (forward/backward substitution) of a factorized linear system. - Mechanical APDL Command: `\*NRM `_ + Mechanical APDL Command: `\*LSBAC `_ Parameters ---------- - name : str - Matrix or vector for which the norm will be computed. This can be a dense matrix (created by the - :ref:`dmat` command), a sparse matrix (created by the :ref:`smat` command) or a vector (created - by the :ref:`vec` command) - - normtype : str - Mathematical norm to use: - - * ``NRM2`` - L2 (Euclidian or SRSS) norm (default). - - * ``NRM1`` - L1 (absolute sum) norm (vectors and dense matrices only). - - * ``NRMINF`` - Maximum norm. - - parr : str - Parameter name that contains the result. + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine` and + factorized using :ref:`lsfactor`. - normalize : str - Normalization key; to be used only for vectors created by :ref:`vec` : + rhsvector : str + Name of vector containing the right-hand side (load) vectors as input. Must have been previously + defined as a :ref:`vec` vector or a :ref:`dmat` matrix. - * ``YES`` - Normalize the vector such that the norm is 1.0. + solvector : str + Name of vector that will contain the solution vectors upon completion. Must be predefined as a + :ref:`vec` vector or :ref:`dmat` matrix. - * ``NO`` - Do not normalize the vector (default). + transkey : str + Transpose key. Set ``TransKey`` = TRANS to solve the transposed linear system. If blank, + transpose will not be used. Notes ----- - The NRM2 option corresponds to the Euclidian or L2 norm and is applicable to either vectors or matrices: - - :math:``, :math:`` - - :math:``, :math:`` where :math:`` is the complex conjugate of :math:`` - - :math:``, :math:`` = largest eigenvalue of :math:`` - - The NRM1 option corresponds to the L1 norm and is applicable to vectors and dense matrices: - - :math:`` or :math:``, :math:`` - - :math:`` or :math:``, :math:`` - - The NRMINF option is the maximum norm and is applicable to either vectors or matrices: - - :math:`` or :math:``, :math:`` - - :math:`` or :math:``, :math:`` + This command performs forward and back substitution to obtain the solution to the linear matrix + equation Ax = b (or A :sup:`T` x = b if ``TransKey`` = TRANS). The matrix engine must have been + previously defined using :ref:`lsengine`, and the matrix factored using :ref:`lsfactor`. You can + use the :ref:`dmat` ,,,COPY (or :ref:`vec` ,,,COPY) command to copy the load vector to the solution + vector in order to predefine it with the appropriate size. """ - command = f"*NRM,{name},{normtype},{parr},{normalize}" + command = f"*LSBAC,{enginename},{rhsvector},{solvector},{transkey}" return self.run(command, **kwargs) - def starprint(self, matrix="", fname="", **kwargs): - r"""Prints the matrix values to a file. + def lsdump(self, enginename: str = "", filename: str = "", **kwargs): + r"""Dumps a linear solver engine to a binary File. - Mechanical APDL Command: `\*PRINT `_ + Mechanical APDL Command: `\*LSDUMP `_ Parameters ---------- - matrix : str - Name of matrix or vector to print. Must be specified. + enginename : str + Name used to identify this engine. Must have been previously created using :ref:`lsengine` and + factorized using :ref:`lsfactor`. - fname : str - File name (case-sensitive, 32-character maximum). If blank, matrix is written to the output - file. + filename : str + Name of the file to create. Notes ----- - The matrix may be a dense matrix ( :ref:`dmat` ), a sparse matrix ( :ref:`smat` ), or a vector ( :ref:`vec` ). Only the non-zero entries of the matrix are printed. + Dumps a previously factorized linear solver system to a binary file. Only LAPACK and BCS linear + solvers can be used with this feature. The Linear Solver can later be restored with the + :ref:`lsrestore` command. A BCS Sparse Solver can be dumped only if uses the ``INCORE`` memory + option (see :ref:`bcsoption` ). Caret 7? """ - command = f"*PRINT,{matrix},{fname}" + command = f"*LSDUMP,{enginename},{filename}" return self.run(command, **kwargs) - def remove(self, name="", val1="", val2="", val3="", **kwargs): + def remove( + self, name: str = "", val1: str = "", val2: str = "", val3: str = "", **kwargs + ): r"""Suppresses rows or columns of a dense matrix or a vector. Mechanical APDL Command: `\*REMOVE `_ @@ -1004,41 +1058,27 @@ def remove(self, name="", val1="", val2="", val3="", **kwargs): name : str Name of the matrix or vector to be revised. - val1, val2, val3 : str + val1 : str Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type (matrix or vector). See details below. - The following ``Val1`` through ``Val3`` fields are used if ``Name`` refers to a dense matrix created by the :ref:`dmat` command: - - val1 : str - First row or column number to suppress. - val2 : str - Last row or column number to suppress. + Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type + (matrix or vector). See details below. val3 : str - Specifies what to remove: - - * ``COL`` - Remove columns of the matrix (default). - - * ``ROW`` - Remove rows of the matrix. - - The following ``Val1`` and ``Val2`` fields are used if ``Name`` refers to a vector created by the :ref:`vec` command: - - val1 : str - First value index to suppress. - - val2 : str - Last value index to suppress. + Additional input. The meaning of ``Val1`` to ``Val3`` varies depending on the entity type + (matrix or vector). See details below. Notes ----- - The values of the original matrix or vector specified by ``Name`` are retained. The matrix or vector is resized to the new number of rows and columns. + The values of the original matrix or vector specified by ``Name`` are retained. The matrix or vector + is resized to the new number of rows and columns. """ command = f"*REMOVE,{name},{val1},{val2},{val3}" return self.run(command, **kwargs) - def starrename(self, oldname="", newname="", **kwargs): + def starrename(self, oldname: str = "", newname: str = "", **kwargs): r"""Renames an existing vector or matrix. Mechanical APDL Command: `\*RENAME `_ @@ -1053,50 +1093,69 @@ def starrename(self, oldname="", newname="", **kwargs): Notes ----- - The :ref:`starrename` command is used to rename `APDL Math `_ objects. + The :ref:`starrename` command is used to rename `APDL Math + `_ objects. """ command = f"*RENAME,{oldname},{newname}" return self.run(command, **kwargs) - def scal(self, name="", val1="", val2="", **kwargs): - r"""Scales a vector or matrix by a constant. + def axpy( + self, + vr: str = "", + vi: str = "", + m1: str = "", + wr: str = "", + wi: str = "", + m2: str = "", + **kwargs, + ): + r"""Performs the matrix operation M2= v\*M1 + w\*M2. - Mechanical APDL Command: `\*SCAL `_ + Mechanical APDL Command: `\*AXPY `_ Parameters ---------- - name : str - Name used to identify the vector or matrix to be scaled. Must be specified. + vr : str + The real and imaginary parts of the scalar ``v``. Default value is 0. - val1 : str - The real part of the constant to use (default = 1). + vi : str + The real and imaginary parts of the scalar ``v``. Default value is 0. - val2 : str - The imaginary part of the constant to use (default = 0). This value is used only if the vector - or matrix specified by ``Name`` is complex. + m1 : str + Name of matrix ``M1``. If not specified, the operation M2 = w\*M2 will be performed. + + wr : str + The real and imaginary parts of the scalar ``w``. Default value is 0. + + wi : str + The real and imaginary parts of the scalar ``w``. Default value is 0. + + m2 : str + Name of matrix ``M2``. Must be specified. Notes ----- - This command can be applied to vectors and matrices created by the :ref:`vec`, :ref:`dmat` and :ref:`smat` commands. + The matrices ``M1`` and ``M2`` must have the same dimensions and same type (dense or sparse). If + ``M2`` is real, ``vi`` and ``wi`` are ignored. """ - command = f"*SCAL,{name},{val1},{val2}" + command = f"*AXPY,{vr},{vi},{m1},{wr},{wi},{m2}" return self.run(command, **kwargs) - def smat( + def dmat( self, - matrix="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", - val5="", + matrix: str = "", + type_: str = "", + method: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", **kwargs, ): - r"""Creates a sparse matrix. + r"""Creates a dense matrix. - Mechanical APDL Command: `\*SMAT `_ + Mechanical APDL Command: `\*DMAT `_ Parameters ---------- @@ -1106,353 +1165,119 @@ def smat( type : str Matrix type: - * ``D`` - Double precision real values (default). - - * ``Z`` - Complex double precision values. + * ``D`` - Double precision real values (default). + * ``Z`` - Complex double precision values. + * ``I`` - Integer values. method : str Method used to create the matrix: - * ``ALLOC`` - Allocate a new matrix. - - * ``COPY`` - Copy an existing matrix. - - * ``IMPORT`` - Import the matrix from a file. - - val1, val2, val3, val4, val5 : str - Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified - ``Method`` . See details below. - - The following ``Valx`` fields are used with ``Method`` = ALLOC. - - val1 : str - Method used to create the matrix: - - * ``DIAG`` - Allocate a diagonal square matrix. ``Val2`` is used; ``Val3``, ``Val4``, and - ``Val5`` are ignored. - - * ``Val2`` - Matrix size. - - * ``CSR`` - Create a square sparse matrix based on Compressed Sparse Row (CSR) format - description vectors. This format requires 3 input vectors specified as ``Val2``, ``Val3`` and - - ``Val4`` . - - * ``Val2, Val3, Val4`` - Names of required row_ptr, col_ind and val vectors. These - vectors - must be created using the :ref:`vec` command. - - row_ptr is a long integer vector (use of L instead of I as the scalar type in the - :ref:`vec` - - call); col_ind is an integer vector. Val can be a real of complex values vector, - according - to - the matrix type. - - * ``Val5`` - Specifies whether the matrix is symmetric (TRUE) or unsymmetric (FALSE). - Default = - TRUE. - - The following ``Valx`` fields are used with ``Method`` = COPY. + * ``ALLOC`` - Allocate space for a matrix (default). + * ``RESIZE`` - Resize an existing matrix to new row and column dimensions. Values are kept from the + original matrix. If the dimensions specified by ``Val1`` (rows) and ``Val2`` (columns) are greater + than the original matrix size, the additional entries are assigned a value of zero. + * ``COPY`` - Copy an existing matrix. + * ``LINK`` - Link to an existing matrix. The memory will be shared between the original matrix and + the new matrix. This is useful for manipulating a submatrix of a larger matrix. The ``Val1`` + through ``Val5`` arguments will be used to specify the lower and upper bounds of row and column + numbers from the original matrix. + * ``IMPORT`` - Import the matrix from a file. val1 : str - Name of the matrix to copy (can be either a dense or a sparse matrix). + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. val2 : str - Method used for copying the matrix: - - * ``DIAG`` - Copy only the diagonal of the matrix. ``Val3`` and ``Val4`` are ignored. - - * ``TRANS`` - Transpose the original matrix. ``Val3`` and ``Val4`` are ignored. - - * ``EXTRACT`` - Extract a submatrix based on row and column numbers specified by ``Val3`` - and - ``Val4`` . + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. val3 : str - Name of integer vector ( :ref:`vec` ) containing row numbers. If no vector is specified, - defaults to all rows. + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. val4 : str - Name of integer vector ( :ref:`vec` ) containing column numbers. If no vector is specified, - defaults to all columns. - - The following table describes the ``Valx`` fields used with ``Method`` = IMPORT. - - InformalTables need to be added. - - Notes - ----- - Use the :ref:`dmat` command to create a dense matrix. - - For more information on the CSR format, see `Creating a Sparse Matrix Using the CSR Format `_ - - For more information on the NOD2SOLV and USR2SOLV mapping vectors, see . - - For more information about ``.FULL`` file contents, see the :ref:`hbmat` in the `Command Reference `_. - """ - command = f"*SMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" - return self.run(command, **kwargs) - - def starsort(self, name="", sorttype="", val1="", val2="", **kwargs): - r"""Sorts the values of the specified vector. - - Mechanical APDL Command: `\*SORT `_ - - Parameters - ---------- - name : str - Name of the vector to be sorted. This vector can contain real or complex values. - - sorttype : str - Criteria used to sort the values: - - * ``VALUE`` - Values are sorted based on their real value (default). - - * ``ABS`` - Values are sorted based on their absolute value. - - * ``PERM`` - Values are sorted based on the input permutation vector ( ``Val1`` ). - - val1, val2 : str - Additional input. The meaning of ``Val1``, ``Val2`` varies depending on the specified - ``SortType`` . See below for details. - - The following ``Valx`` fields are used with ``SortType`` = VALUE or ABS: - - val1 : str - Name of the vector in which permutation values will be saved (optional). This should be an empty - vector of type integer that was created with the :ref:`vec` command. The size of this - permutation vector must be identical to the size of the vector to be sorted. After the sort, - this vector contains the permutation used to sort the values. - - val2 : str - Order of the sort operation: - - * ``0`` - Increasing order (default). - - * ``1`` - Decreasing order. - - The following ``Valx`` fields are used with ``Method`` = PERM: - - val1 : str - Name of the permutation vector used to sort the values. This must be a vector of integer values - that was created with the :ref:`vec` command. The size of this permutation vector must be - identical to the size of the vector to be sorted. + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. - This permutation vector is required when using ``Method`` = PERM. + val5 : str + Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified + ``Method``. See details below. Notes ----- - The examples below demonstrate using :ref:`starsort` to sort the values of an input vector. - - The following input: + This command allows you to create a dense matrix. To create a sparse matrix, use the :ref:`smat` command. :ref:`smat` is recommended for large matrices obtained from the ``.FULL`` or ``.HBMAT`` file. Refer to the :ref:`hbmat` command documentation for more information about ``.FULL`` file contents. - .. code:: + Use the :ref:`vec` command to create a vector. - \*VEC,V,I,ALLOC,5 - V(1)=5,-3,2,0,-1 - \*SORT,V,VALUE - \*PRINT,V + For very large matrices, use the OUTOFCORE option ( ``Method`` = ALLOC or COPY) to keep some of the matrix on disk if there is insufficient memory. - generates this output: + When importing a dense matrix from a DMIG file, you can define the formatting of the file using the ``Val3`` and ``Val4`` fields. Here are a few different example of formats: + A LARGE field format file (using ``Val3`` = ’LARGE’): .. code:: - - -3 -1 0 2 5 - - To reverse the order, this input: - + ... + DMIG\* KAAX 21 2 + * 21 1-2.261491337E+08 + ... + A FREE field format file with blank separators (using ``Val4`` = ’S’): .. code:: - - \*SORT,V,VALUE,,1 - \*PRINT,V - - generates this output: - + ... + DMIG stiff 1 2 1 2 29988. + 1 6 149940. 2 2 -29988. + 2 6 149940. + ... + A FREE field format file with a comma separator (using ``Val4`` = ’,’): .. code:: + ... + DMIG,KF,22321,3,,22321,2,-5.00E+6 + DMIG,KF,22320,3,,22320,2,-5.00E+6 + ... - 5 2 0 -1 -3 + Requirement when importing matrices from a Nastran DMIG file: To ensure that the ``.sub`` file is properly generated from matrices imported from Nastran DMIG file, the generalized coordinates for a CMS superelement (SPOINTS in Nastran) must appear last (have + highest ID number). """ - command = f"*SORT,{name},{sorttype},{val1},{val2}" + command = f"*DMAT,{matrix},{type_},{method},{val1},{val2},{val3},{val4},{val5}" return self.run(command, **kwargs) - def vec( + def dot( self, - vector="", - type_="", - method="", - val1="", - val2="", - val3="", - val4="", + vector1: str = "", + vector2: str = "", + par_real: str = "", + par_imag: str = "", + conj: str = "", **kwargs, ): - r"""Creates a vector. - - Mechanical APDL Command: `\*VEC `_ - - Parameters - ---------- - vector : str - Name used to identify the vector. Must be specified. - - type : str - Vector type: - - * ``D`` - Double precision real values (default). - - * ``Z`` - Complex double precision values. - - * ``I`` - Integer values. - - method : str - Method used to create the vector: - - * ``ALLOC`` - Allocate space for a vector (default). - - * ``RESIZE`` - Resize an existing vector to a new length. Values are kept from the original - vector. If the length specified by ``Val1`` is greater than the original vector length, the - additional rows are assigned a value of zero. - - * ``COPY`` - Copy an existing vector. - - * ``IMPORT`` - Import the vector from a file. - - * ``LINK`` - Link to a column of an existing dense :ref:`dmat` matrix and use it in - subsequent - vector calculations. Any changes to the vector are also made to the corresponding matrix - column - (memory is shared). - - val1, val2, val3, val4, val5 : str - Additional input. The meaning of ``Val1`` through ``Val5`` will vary depending on the specified - ``Method`` . See details below. - - The following ``Valx`` field is used with ``Method`` = ALLOC or ``Method`` = RESIZE: - - val1 : str - Number of rows in the vector. - - The following ``Valx`` field is used with ``Method`` = COPY: - - val1 : str - Name of the vector to copy. - - val2 : str - Optional argument to specify either the real or the imaginary part of the values to be copied. - This option only applies when copying a complex value vector to a real value vector. - - * ``REAL`` - Copy the real part of the vector to the output vector. - - * ``IMAG`` - Copy the imaginary part of the vector to the output vector. - - The following table describes the ``Valx`` fields used with ``Method`` = IMPORT. - - InformalTables need to be added. - The following ``Valx`` fields are used with ``Method`` = LINK: - - val1 : str - Name of the :ref:`dmat` matrix. - - val2 : str - Column number of the matrix to link to. - - Notes - ----- - Use the :ref:`dmat` command to create a matrix. - - For more information on the BACK and FORWARD nodal mapping vectors, see in the `Ansys Parametric Design Language Guide `_. - """ - command = f"*VEC,{vector},{type_},{method},{val1},{val2},{val3},{val4}" - return self.run(command, **kwargs) - - def wrk(self, num="", **kwargs): - r"""Sets the active workspace number. - - Mechanical APDL Command: `\*WRK `_ - - Parameters - ---------- - num : str - Number of the active memory workspace for APDLMath vector and matrices. All the following - APDLMath vectors and matrices will belong to this memory workspace, until the next call to the - :ref:`wrk` command. By default, all the APDLMath objects belong to workspace number 1. - - Notes - ----- - This feature enables you to associate a set of vector and matrices in a given memory workspace, so that you can easily manage the free step: - - .. code:: - - \*VEC,V,D,ALLOC,5 ! V belongs to the default Workspace 1 - - \*WRK,2 ! Set the active workspace as the number 2 - - \*VEC,W,D,IMPORT,FULL,file.full,RHS ! W belongs to the Workspace 2 - \*SMAT,K,D,IMPORT,FULL,file.full,STIFF ! K belongs to the Workspace 2 - \*DMAT,M,ALLOC,10,10 ! M belongs to the Workspace 2 - … - \*FREE,WRK,2 ! W, K and M are deleted, but not V - - \*PRINT,V - - This feature can be useful to free all the temporary APDLMath variables inside a MACRO in one call. - """ - command = f"*WRK,{num}" - return self.run(command, **kwargs) - - def xpl(self, action="", val1="", val2="", **kwargs): - r"""Accesses content of a Mechanical APDL file. + r"""Computes the dot (or inner) product of two vectors. - Mechanical APDL Command: `\*XPL `_ + Mechanical APDL Command: `\*DOT `_ Parameters ---------- - action : str - Specifies the action for scanning file content (no default). Valid labels are: - - * ``OPEN`` - Open the specified file. - - * ``CLOSE`` - Close the specified file. - - * ``LIST`` - List the records at the current level in the hierarchy of records. - - * ``WHERE`` - Display the current location in the tree. - - * ``STEP`` - Step down in the tree of records. - - * ``UP`` - Go up in the tree of records. - - * ``READ`` - Read a record into an APDL Math object. - - * ``INFO`` - Display information from a record. - - * ``GOTO`` - Move directly to a given place in the tree of records (this avoids multiple - calls - to the STEP and UP options). + vector1 : str + Name of first vector; must have been previously specified by a :ref:`vec` command. - * ``MARK`` - Mark a set of records of the current file; the asterisk (\*) character can be - used - to specify multiple branches/records. + vector2 : str + Name of second vector; must have been previously specified by a :ref:`vec` command. - * ``COPY`` - Copy the current file to a new one, ignoring the marked records. + par_real : str + Parameter name that contains the result. - * ``SAVE`` - Save the current file, ignoring the marked records. + par_imag : str + Parameter name that contains the imaginary part of the result (used only for complex vectors). - val1, val2 : str - Additional input. The meanings of ``Val1`` and ``Val2`` vary depending on the specified - ``Action``, as described in the table below. + conj : str + Key to specify use of the conjugate of ``Vector1`` when the vectors are complex: - InformalTables need to be added. + * ``TRUE`` - Use the conjugate of ``Vector1`` (default). + * ``FALSE`` - Do not use the conjugate of ``Vector1``. Notes ----- - The :ref:`xpl` command enables you to explore the contents of a Mechanical APDL file. Use this command to traverse up and down the tree structure of the specified file and review what is in the file. Files that can be scanned include ``.RST``, ``.MODE``, ``.FULL``, ``.CMS``, and ``.SUB`` files. For more information and examples, see `Using APDL to List File Structure and Content `_ - - The command :ref:`xpl` ,READ generates either a :ref:`vec` or a :ref:`dmat` object according to the record type. You do not have to create the APDL Math object before issuing this command. - - This command is valid in any processor. + If ``Vector1`` and ``Vector2`` are complex, the complex conjugate of ``Vector1`` is used to compute + the result ( ``Par_Real``, ``Par_Imag`` ). Therefore, \*DOT applied to complex vectors performs the + operation: .. math:: Set ``Conj`` = FALSE if you do not want to use the conjugate of + ``Vector1``. In this case, the operation is: .. math:: """ - command = f"*XPL,{action},{val1},{val2}" + command = f"*DOT,{vector1},{vector2},{par_real},{par_imag},{conj}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/parameters.py b/src/ansys/mapdl/core/_commands/apdl/parameters.py index 4507a72124..f61c1fe7b2 100644 --- a/src/ansys/mapdl/core/_commands/apdl/parameters.py +++ b/src/ansys/mapdl/core/_commands/apdl/parameters.py @@ -23,254 +23,82 @@ class Parameters: - def afun(self, lab="", **kwargs): - r"""Specifies units for angular functions in parameter expressions. + def parres(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Reads parameters from a file. - Mechanical APDL Command: `\*AFUN `_ + Mechanical APDL Command: `PARRES `_ Parameters ---------- lab : str - Specifies the units to be used: - - * ``RAD`` - Use radians for input and output of parameter angular functions (default). - - * ``DEG`` - Use degrees for input and output of parameter angular functions. - - * ``STAT`` - Show current setting (DEG or RAD) for this command. - - Use radians for input or output of parameter angular functions. - - Notes - ----- - Only the SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2, ANGLEK, and ANGLEN functions ( :ref:`starset`, :ref:`vfun` ) are affected by this command. - """ - command = f"*AFUN,{lab}" - return self.run(command, **kwargs) - - def ask(self, par="", query="", dval="", **kwargs): - r"""Prompts the user to input a parameter value. - - Mechanical APDL Command: `\*ASK `_ + Read operation: - Parameters - ---------- - par : str - An alphanumeric name used to identify the scalar parameter. See :ref:`starset` for name - restrictions. + * ``NEW`` - Replace current parameter set with these parameters (default). + * ``CHANGE`` - Extend current parameter set with these parameters, replacing any that already exist. - query : str - Text string to be displayed on the next line as the query (32 characters maximum). Characters - having special meaning (such as $ ! ) should not be included. + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. The file name defaults to ``Jobname``. - dval : str - Default value assigned to the parameter if the user issues a blank response. May be a number or - character string (up to 8 characters enclosed in single quotes). If a default is not assigned, a - blank response will delete the parameter. + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is blank. Notes ----- - Intended primarily for use in macros, the command prints the query (after the word ``ENTER`` ) on the next line and waits for a response. The response is read from the keyboard, except in batch mode ( :ref:`batch` ), when the response(s) must be the next-read input line(s). The response may be a number, a character string (up to 8 characters enclosed in single quotes), a parameter (numeric or character) or an expression that evaluates to a number. The scalar parameter is then set to the response value. For example, :ref:`ask` ,NN,PARAMETER NN will set NN to the value entered on the next line (after the prompt ``ENTER PARAMETER NN`` ). - - The :ref:`ask` command is not written to ``File.LOG``, but the responses are written there as follows: If :ref:`ask` is contained in a macro, the response(s) (only) is written to ``File.LOG`` on the line(s) following the macro name. If not contained in a macro, the response is written to ``File.LOG`` as a parameter assignment (that is, ``Par`` = "user-response"). + Reads parameters from a coded file. The parameter file may have been written with the :ref:`parsav` + command. The parameters read may replace or change the current parameter set. This command is valid + in any processor. - If used within a do-loop that is executed interactively, :ref:`ask` should be contained in a macro. If not contained in a macro, :ref:`ask` will still query the user as intended, but the resulting log file will `not` reproduce the effects of the original run. + Examples + -------- + Read a local parameter file. - This command is valid in any processor. + >>> mapdl.parres('parm.PARM') """ - command = f"*ASK,{par},{query},{dval}" - return self.run(command, **kwargs) + return self.run(f"PARRES, {lab}, {fname}, {ext}") - def dim( - self, - par="", - type_="", - imax="", - jmax="", - kmax="", - var1="", - var2="", - var3="", - csysid="", - **kwargs, - ): - r"""Defines an array parameter and its dimensions. + def parsav(self, lab: str = "", fname: str = "", ext: str = "", **kwargs): + r"""Writes parameters to a file. - Mechanical APDL Command: `\*DIM `_ + Mechanical APDL Command: `PARSAV `_ Parameters ---------- - par : str - Name of parameter to be dimensioned. See :ref:`starset` for name restrictions. - - type : str - Array type: - - * ``ARRAY`` - Arrays are similar to standard FORTRAN arrays (indices are integers) - (default). - Index numbers for the rows, columns, and planes are sequential values beginning with one. Used - for - 1-, 2-, or 3D arrays. - - * ``ARR4`` - Same as ARRAY, but used to specify 4-D arrays. - - * ``ARR5`` - Same as ARRAY, but used to specify 5-D arrays. - - * ``CHAR`` - Array entries are character strings (up to 8 characters each). Index numbers - for - rows, columns, and planes are sequential values beginning with one. - - * ``TABLE`` - Array indices are real (non-integer) numbers which must be defined when - filling - the table. Index numbers for the rows and columns are stored in the zero column and row "array - - elements" and are initially assigned a near-zero value. Index numbers must be in ascending - order - and are used only for retrieving an array element. When retrieving an array element with a - real - index that does not match a specified index, linear interpolation is done among the nearest - indices and the corresponding array element values ( :ref:`starset` ). Used for 1-, 2-, or 3D - tables. - - * ``TAB4`` - Same as TABLE, but used to specify 4-D tables. - - * ``TAB5`` - Same as TABLE, but used to specify 5-D tables. - - * ``STRING`` - Array entries are character strings (up to IMAX each). Index numbers for - columns - and planes are sequential values beginning with 1. Row index is character position in string. - - imax : str - Extent of first dimension (row). (For ``Type`` = STRING, ``IMAX`` is rounded up to the next - multiple of eight and has a limit of 248). Default = 1. - - jmax : str - Extent of second dimension (column). Default = 1. - - kmax : str - Extent of third dimension (plane). Default = 1. - - var1 : str - Variable name corresponding to the first dimension (row) for ``Type`` = TABLE, TAB4, or TAB5. - Default = Row. + lab : str + Write operation: - var2 : str - Variable name corresponding to the second dimension (column) for ``Type`` = TABLE, TAB4, or - TAB5. Default = Column. + * ``SCALAR`` - Write only scalar parameters (default). + * ``ALL`` - Write scalar and array parameters. Parameters may be numeric or alphanumeric. - var3 : str - Variable name corresponding to the third dimension (plane) for ``Type`` = TABLE, TAB4, TAB5. - Default = Plane. + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. The file name defaults to ``Jobname``. - csysid : str - An integer corresponding to the coordinate system ID number. Default = 0 (global Cartesian). + ext : str + Filename extension (eight-character maximum). The extension defaults to PARM if ``Fname`` is blank. Notes ----- - Up to three dimensions (row, column, and plane) may be defined using ARRAY and TABLE. Use ARR4, ARR5, TAB4, and TAB5 to define up to five dimensions (row, column, plane, book, and shelf). An index number is associated with each row, column, and plane. For array and table type parameters, element values are initialized to zero. For character and string parameters, element values are initialized to (blank). A defined parameter must be deleted ( :ref:`starset` ) before its dimensions can be changed. Scalar (single valued) parameters should not be dimensioned. :ref:`dim` ,A,,3 defines a vector array with elements A(1), A(2), and A(3). :ref:`dim` ,B,,2,3 defines a 2x3 array with elements B(1,1), B(2,1), B(1,2), B(2,2), B(1,3), and B(2,3). Use :ref:`starstatus`, ``Par`` to display elements of array ``Par`` . You can write formatted data files (tabular formatting) from data held in arrays through the :ref:`vwrite` command. - - If you use table parameters to define boundary conditions, then ``Var1``, ``Var2``, and/or ``Var3`` can either specify a primary variable (listed in ) or can be an independent parameter. If specifying an independent parameter, then you must define an additional table for the independent parameter. The additional table must have the same name as the independent parameter and may be a function of one or more primary variables or another independent parameter. All independent parameters must relate to a primary variable. - - Tabular load arrays can be defined in both global Cartesian (default), cylindrical, spherical, or local (see below) coordinate systems by specifying ``CSYSID``, as defined in :ref:`local` . Coordinate system ``CSYSID`` must exist prior to issuing the :ref:`dim` command. - - The following constraints apply when specifying a local coordinate system for your tabular loads: - - Only Cartesian, cylindrical and spherical coordinate systems are supported - Angle values for Y in cylindrical or spherical coordinate systems must be input in degrees and must - be positive values between 0 and 360 degrees (0 :math:`` Y :math:`` 360) - Angle values for Z in spherical coordinate system must be input in degrees and must be positive - values between -90 and +90 ( -90 :math:`` Z :math:`` 90) - - If specifying a 4- or 5-D array or table, four additional fields ( ``LMAX``, ``MMAX``, ``Var4``, and ``Var5`` ) are available. Thus, for a 4-D table, the command syntax would be: - - .. code:: - - \*DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,Var1,Var2,Var3,Var4,CSYSID - - For a 5-D table, the command syntax is: - - .. code:: - - \*DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,MMAX,Var1,Var2,Var3,Var4,Var5,CSYSID - - You cannot create or edit 4- or 5-D arrays or tables via the GUI. - - For more information, see `Array Parameters `_ - - **\*DIM - Primary Variables** - - .. flat-table:: - :header-rows: 1 - - * - Primary Variable - - Label for ``Var1, Var2, Var3, Var4, Var5`` - * - Time - - TIME - * - Frequency - - FREQ - * - X-coordinate location - - X - * - Y-coordinate location - - Y - * - Z-coordinate location - - Z - * - Temperature - - TEMP - * - Velocity - - VELOCITY - * - Pressure - - PRESSURE [ ] - * - Geometric gap/penetration - - GAP - * - Cyclic sector number - - SECTOR - * - Amplitude of the rotational velocity vector - - OMEGS - * - Eccentricity - - ECCENT - * - Phase shift - - THETA - * - Element number - - ELEM - * - Node number - - NODE - * - Concentration - - CONC - - Specify PRESSURE as the independent variable (not PRES). - - The X, Y, and Z coordinate locations listed above are valid in global Cartesian, or local (Cartesian, cylindrical and spherical) coordinate systems. The VELOCITY label is applicable only to the calculated fluid velocity in element FLUID116 . - - When using PRESSURE as a primary variable, the underlying element must have the pressure DOF associated with it, or it must be a supported contact element. - - The gap/penetration label (GAP) is only used for defining certain contact element real constants. - - The frequency label (FREQ) is valid for harmonic analyses only. - - The node and element labels (NODE and ELEM) allow you to use node and element numbers as primary variables, and their axis values should be integers. - - The OMEGS, ECCENT, and THETA primary variables only apply to the COMBI214 element. The amplitude of the rotational velocity (OMEGS) is an absolute value, so only positive values of OMEGS are valid. The eccentricity (ECCENT) and phase shift (THETA) labels are only valid for nonlinear analyses. - - If you use table parameters to define boundary conditions, the table names ( ``Par`` ) must not exceed 32 characters. - - In thermal analyses, if you apply tabular loads as a function of temperature but the rest of the model is linear (for example, includes no temperature-dependent material properties or radiation ), you should turn on Newton-Raphson iterations ( :ref:`nropt` ,FULL) to evaluate the temperature-dependent tabular boundary conditions correctly. - - This command is valid in any processor. + Writes the current parameters to a coded file. Previous parameters on this file, if any, will be + overwritten. The parameter file may be read with the :ref:`parres` command. :ref:`parsav` / + :ref:`parres` operations truncate some long decimal strings, and can cause differing values in your + solution data when other operations are performed. A good practice is to limit the number of decimal + places you will use before and after these operations. This command is valid in any processor. """ - command = ( - f"*DIM,{par},{type_},{imax},{jmax},{kmax},{var1},{var2},{var3},{csysid}" - ) + command = f"PARSAV,{lab},{fname},{ext}" return self.run(command, **kwargs) def get( self, - par="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", + par: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", **kwargs, ): r"""Retrieves a value and stores it as a scalar parameter or part of an array parameter. @@ -296,10 +124,14 @@ def get( it1num : str The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown - in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an + in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an ``IT1NUM`` value. - item2, it2num : str + item2 : str + A second set of item labels and numbers to further qualify the item for which data are to be + retrieved. Most items do not require this level of information. + + it2num : str A second set of item labels and numbers to further qualify the item for which data are to be retrieved. Most items do not require this level of information. @@ -310,23 +142,29 @@ def get( Notes ----- - :ref:`get` retrieves a value for a specified item and stores the value as a scalar parameter, or as a value in a user-named array parameter. An item is identified by various keyword, label, and number combinations. Usage is similar to the :ref:`starset` command except that the parameter values are retrieved from previously input or calculated results. - - :ref:`get` Usage :ref:`get` ,A,ELEM,5,CENT,X returns the centroid x location of element 5 and stores the result as parameter A. - - :ref:`get` command operations, and corresponding get functions, return values in the active coordinate system ( :ref:`csys` for input data or :ref:`rsys` for results data) unless stated otherwise. - - A get function is an alternative in-line function that can be used instead of the :ref:`get` command to retrieve a value. For more information, see . - - Both :ref:`get` and :ref:`starvget` retrieve information from the active data stored in memory. The database is often the source, and sometimes the information is retrieved from common memory blocks that the program uses to manipulate information. Although POST1 and POST26 operations use a ``\*.rst`` file, :ref:`get` data is accessed from the database or from the common blocks. Get operations do not access the ``\*.rst`` file directly. For repeated gets of sequential items, such as from a series of elements, see the :ref:`starvget` command. - - Most items are stored in the database after they are calculated and are available anytime thereafter. Items are grouped according to where they are usually first defined or calculated. Preprocessing data will often not reflect the calculated values generated from section data. Do not use :ref:`get` to obtain data from elements that use calculated section data, such as beams or shells. - - When the value retrieved by :ref:`get` is a component name, the resulting character parameter is limited to 32 characters. If the component name is longer than 32 characters, the remaining characters are ignored. - - Most of the `general` items listed below are available from all modules. Each of the sections for accessing :ref:`get` parameters are shown in the following order: - - The :ref:`get` command is valid in any processor. + :ref:`get` retrieves a value for a specified item and stores the value as a scalar parameter, or as + a value in a user-named array parameter. An item is identified by various keyword, label, and number + combinations. Usage is similar to the :ref:`starset` command except that the parameter values are + retrieved from previously input or calculated results. :ref:`get` Usage :ref:`get` ,A,ELEM,5,CENT,X + returns the centroid x location of element 5 and stores the result as parameter A. :ref:`get` + command operations, and corresponding get functions, return values in the active coordinate system ( + :ref:`csys` for input data or :ref:`rsys` for results data) unless stated otherwise. A get function + is an alternative in-line function that can be used instead of the :ref:`get` command to retrieve a + value. For more information, see. Both :ref:`get` and :ref:`starvget` retrieve information from the + active data stored in memory. The database is often the source, and sometimes the information is + retrieved from common memory blocks that the program uses to manipulate information. Although POST1 + and POST26 operations use a ``\*.rst`` file, :ref:`get` data is accessed from the database or from + the common blocks. Get operations do not access the ``\*.rst`` file directly. For repeated gets of + sequential items, such as from a series of elements, see the :ref:`starvget` command. Most items + are stored in the database after they are calculated and are available anytime thereafter. Items are + grouped according to where they are usually first defined or calculated. Preprocessing data will + often not reflect the calculated values generated from section data. Do not use :ref:`get` to obtain + data from elements that use calculated section data, such as beams or shells. When the value + retrieved by :ref:`get` is a component name, the resulting character parameter is limited to 32 + characters. If the component name is longer than 32 characters, the remaining characters are + ignored. Most of the `general` items listed below are available from all modules. Each of the + sections for accessing :ref:`get` parameters are shown in the following order: The :ref:`get` + command is valid in any processor. Examples -------- @@ -346,7 +184,17 @@ def get( command = f"*GET,{par},{entity},{entnum},{item1},{it1num},{item2},{it2num}" return self.run(command, **kwargs) - def slashinquire(self, strarray="", func="", **kwargs): + def slashinquire( + self, + strarray: str = "", + func: str = "", + envname: str = "", + substring: str = "", + parameter: str = "", + fname: str = "", + ext: str = "", + **kwargs, + ): r"""Returns system information to a parameter. Mechanical APDL Command: `/INQUIRE `_ @@ -355,42 +203,26 @@ def slashinquire(self, strarray="", func="", **kwargs): ---------- strarray : str Name of the "string array" parameter that will hold the returned values. String array parameters - are similar to character arrays, but each array element can be as long as 248 characters. If - the string parameter does not exist, it will be created. + are similar to character arrays, but each array element can be as long as 248 characters. If the + string parameter does not exist, it will be created. func : str Specifies the type of system information returned: - * ``LOGIN`` - Returns the pathname of the login directory on Linux systems or the pathname - of - the default directory (including drive letter) on Windows systems. - - * ``DOCU`` - Returns the pathname of the Mechanical APDL docu directory. - - * ``APDL`` - Returns the pathname of the Mechanical APDL APDL directory. - - * ``PROG`` - Returns the pathname of the Mechanical APDL executable directory. - - * ``AUTH`` - Returns the pathname of the directory in which the license file resides. - - * ``USER`` - Returns the name of the user currently logged-in. - - * ``DIRECTORY`` - Returns the pathname of the current directory. - - * ``JOBNAME`` - Returns the current ``Jobname`` . - - * ``RSTDIR`` - Returns rst directory ( :ref:`file` command). - - * ``RSTFILE`` - Returns rst file name ( :ref:`file` command). - - * ``RSTEXT`` - Returns rst file extension ( :ref:`file` command). - - * ``PSEARCH`` - Returns path used for "unknown command" macro ( :ref:`psearch` command). - - * ``OUTPUT`` - Returns the current output file name ( :ref:`output` command). - - Returning the Value of an Environment Variable to a Parameter - If ``FUNC`` =ENV, the command format is :ref:`slashinquire`, ``StrArray`` ,ENV, ``ENVNAME``, ``Substring`` . In this instance, ENV specifies that the command should return the value of an environment variable. The following defines the remaining fields: + * ``LOGIN`` - Returns the pathname of the login directory on Linux systems or the pathname of the + default directory (including drive letter) on Windows systems. + * ``DOCU`` - Returns the pathname of the Mechanical APDL docu directory. + * ``APDL`` - Returns the pathname of the Mechanical APDL APDL directory. + * ``PROG`` - Returns the pathname of the Mechanical APDL executable directory. + * ``AUTH`` - Returns the pathname of the directory in which the license file resides. + * ``USER`` - Returns the name of the user currently logged-in. + * ``DIRECTORY`` - Returns the pathname of the current directory. + * ``JOBNAME`` - Returns the current ``Jobname``. + * ``RSTDIR`` - Returns rst directory ( :ref:`file` command). + * ``RSTFILE`` - Returns rst file name ( :ref:`file` command). + * ``RSTEXT`` - Returns rst file extension ( :ref:`file` command). + * ``PSEARCH`` - Returns path used for "unknown command" macro ( :ref:`psearch` command). + * ``OUTPUT`` - Returns the current output file name ( :ref:`output` command). envname : str Specifies the name of the environment variable. @@ -401,41 +233,14 @@ def slashinquire(self, strarray="", func="", **kwargs): character is semicolon (;). If this argument is either blank or 0, the entire value of the environment variable is returned. - Returning the Value of a Title to a Parameter - If ``FUNC`` = TITLE, the command format is :ref:`slashinquire`, ``StrArray`` ,TITLE, ``Title_num`` . In this context, the value of ``Title_num`` can be blank or 1 through 5. If the value is 1 or blank, the title is returned. If the value is 2 through 5, a corresponding subtitle is returned (2 denoting the first subtitle, and so on). - - Returning Information About a File to a Parameter - The :ref:`slashinquire` command can also return information about specified files within the file system. For these capabilities, the format is :ref:`slashinquire`, ``Parameter``, ``FUNC`` ,``Fname`` , ``Ext`` , ``--``. The following defines the fields: - parameter : str Name of the parameter that will hold the returned values. - func : str - Specifies the type of file information returned: - - * ``EXIST`` - Returns a 1 if the specified file exists, and 0 if it does not. - - * ``DATE`` - Returns the date stamp of the specified file in the format ``yyyymmdd.hhmmss`` - . - - * ``SIZE`` - Returns the size of the specified file in MB. - - * ``WRITE`` - Returns the status of the write attribute. A 0 denotes no write permission - while a - 1 denotes write permission. - - * ``READ`` - Returns the status of the read attribute. A 0 denotes no read permission while - a 1 - denotes read permission. - - * ``EXEC`` - Returns the status of the execute attribute (this has meaning only on Linux). A - 0 - denotes no execute permission while a 1 denotes execute permission. - - * ``LINES`` - Returns the number of lines in an ASCII file. - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. + ext : str Filename extension (eight-character maximum). @@ -443,212 +248,214 @@ def slashinquire(self, strarray="", func="", **kwargs): ----- The :ref:`slashinquire` command is valid in any processor. """ - command = f"/INQUIRE,{strarray},{func}" + command = f"/INQUIRE,{strarray},{func},{envname},{substring},{parameter},{fname},{ext}" return self.run(command, **kwargs) - def parres(self, lab="", **kwargs): - r"""Reads parameters from a file. + def starset( + self, + par: str = "", + value: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + val10: str = "", + **kwargs, + ): + r"""Assigns values to user-named parameters. - Mechanical APDL Command: `PARRES `_ + Mechanical APDL Command: `\*SET `_ Parameters ---------- - lab : str - Read operation: - - * ``NEW`` - Replace current parameter set with these parameters (default). + par : str + An alphanumeric name used to identify this parameter. ``Par`` can contain up to 32 characters, + beginning with a letter and containing only letters, numbers, and underscores. `Examples:` ABC + A3X TOP_END Command names, function names, label names, component and assembly names, etc., are + invalid, as are parameter names beginning with an underscore (for example, _LOOP ). Parameter + names ending in an underscore are not listed by the :ref:`starstatus` command. Array parameter + names must be followed by a subscript, and the entire expression must be 32 characters or less. + `Examples:` A(1,1) NEW_VAL(3,2,5) RESULT(1000) There is no character parameter substitution + for the ``Par`` field. Table parameters used in command fields (where constant values are + normally given) are limited to 32 characters. - * ``CHANGE`` - Extend current parameter set with these parameters, replacing any that - already - exist. + value : str + Numerical value or alphanumeric character string (up to 32 characters enclosed in single quotes) + to be assigned to this parameter. Examples: A(1,3)=7.4 B='ABC3' Can also be a parameter or a + parametric expression. `Examples:` C=A(1,3) A(2,2)=(C+4)/2. If ``VALUE`` is the table array + name, the subscripts are the values of the primary variables and the table is evaluated at these + specified index values. If blank, delete this parameter. `Example:` A= deletes parameter A. - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - The file name defaults to ``Jobname`` . + val2 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - ext : str - Filename extension (eight-character maximum). - The extension defaults to PARM if ``Fname`` is blank. + val3 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - Notes - ----- - Reads parameters from a coded file. The parameter file may have been written with the :ref:`parsav` command. The parameters read may replace or change the current parameter set. + val4 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - This command is valid in any processor. + val5 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - Examples - -------- - Read a local parameter file. + val6 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - >>> mapdl.parres('parm.PARM') - """ - return self.run(f"PARRES, {lab}, {fname}, {ext}") - - def parsav(self, lab="", **kwargs): - r"""Writes parameters to a file. - - Mechanical APDL Command: `PARSAV `_ - - Parameters - ---------- - lab : str - Write operation: - - * ``SCALAR`` - Write only scalar parameters (default). - - * ``ALL`` - Write scalar and array parameters. Parameters may be numeric or alphanumeric. - - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - The file name defaults to ``Jobname`` . - - ext : str - Filename extension (eight-character maximum). - The extension defaults to PARM if ``Fname`` is blank. - - Notes - ----- - Writes the current parameters to a coded file. Previous parameters on this file, if any, will be overwritten. The parameter file may be read with the :ref:`parres` command. - - :ref:`parsav` / :ref:`parres` operations truncate some long decimal strings, and can cause differing values in your solution data when other operations are performed. A good practice is to limit the number of decimal places you will use before and after these operations. - - This command is valid in any processor. - """ - command = f"PARSAV,{lab}" - return self.run(command, **kwargs) - - def starset( - self, - par="", - value="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", - **kwargs, - ): - r"""Assigns values to user-named parameters. - - Mechanical APDL Command: `\*SET `_ - - Parameters - ---------- - par : str - An alphanumeric name used to identify this parameter. ``Par`` can contain up to 32 characters, - beginning with a letter and containing only letters, numbers, and underscores. `Examples:` ABC - A3X TOP_END - - Command names, function names, label names, component and assembly names, etc., are invalid, as - are parameter names beginning with an underscore (for example, _LOOP ). - - Parameter names ending in an underscore are not listed by the :ref:`starstatus` command. Array - parameter names must be followed by a subscript, and the entire expression must be 32 characters - or less. `Examples:` A(1,1) NEW_VAL(3,2,5) RESULT(1000) - - There is no character parameter substitution for the ``Par`` field. Table parameters used in - command fields (where constant values are normally given) are limited to 32 characters. + val7 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - value : str - Numerical value or alphanumeric character string (up to 32 characters enclosed in single quotes) - to be assigned to this parameter. Examples: A(1,3)=7.4 B='ABC3' Can also be a parameter or a - parametric expression. `Examples:` C=A(1,3) A(2,2)=(C+4)/2 . If ``VALUE`` is the table array - name, the subscripts are the values of the primary variables and the table is evaluated at these - specified index values. + val8 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - If blank, delete this parameter. `Example:` A= deletes parameter A . + val9 : str + If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank + value) are sequentially assigned to the succeeding array elements of the column. `Examples:` + \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns + B(2,3)='file10', B(3,3)='file11'. - val2, val3, val4, val5, val6, val7, val8, val9, val10 : str + val10 : str If ``Par`` is an array parameter, values ``VAL2`` through ``VAL10`` (up to the last nonblank value) are sequentially assigned to the succeeding array elements of the column. `Examples:` \*SET,A(1,4),10,11 assigns A(1,4)=10, A(2,4)=11, and \*SET,B(2,3),'file10','file11' assigns - B(2,3)='file10', B(3,3)='file11' . + B(2,3)='file10', B(3,3)='file11'. Notes Notes ----- - Assigns values to user-named parameters that can be substituted later in the run. The equivalent (and recommended) format is ``Par`` = ``VALUE``, ``VAL2``, ``VAL3``, . . ., ``VAL10`` - - which can be used in place of :ref:`starset`, ``Par``, ... for convenience. - - This command is valid in any processor. - - Parameters (numeric or character) can be scalars (single valued) or arrays (multiple valued in one, two, or three dimensions). An unlimited number of parameter names can be defined in any run. For very large numbers of parameters, it is most efficient to define them in alphabetical order. - - Parameter values can be redefined at any time. Array parameters can also be assigned values within a do-loop ( :ref:`do` ) for convenience. Internally programmed do-loop commands are also available with the \*V ``XX`` commands ( :ref:`vfill` ). Parameter values (except for parameters ending in an underscore) can be listed with the :ref:`starstatus` command, displayed via :ref:`starvplot` (numeric parameters only), and modified via :ref:`vedit` (numeric parameters only). - - Older program-provided macro files can use parameter names that do not begin with an underscore. Using these macros embedded in your own macros may cause conflicts if the same parameter names are used. - - Parameters can also be resolved in comments created via :ref:`com` . A parameter can be deleted by redefining it with a blank ``VALUE`` . If the parameter is an array, the entire array is deleted. Parameters can also be defined by a response to a query via :ref:`ask` or from a Mechanical APDL-provided value via :ref:`get` . - - Array parameters must be dimensioned ( :ref:`dim` ) before being assigned values unless they are the result of an array operation or defined using the implied loop convention. - - Undefined scalar parameters are initialized to a near-zero value. Numeric array parameters are initialized to zero when dimensioned, and character array parameters are initialized to blank. - - An existing array parameter must be deleted before it can be redimensioned. - - Array parameter names must be followed by a subscript list (enclosed in parentheses) identifying the element of the array. The subscript list can have one, two, or three values (separated by commas). Typical array parameter elements are A(1,1), NEW_VAL(3,2,5), RESULT(1000). Subscripts for defining an array element must be integers (or parameter expressions that evaluate to integers). Non-integer values are rounded to the nearest integer value. - - All array parameters are stored as 3D arrays with the unspecified dimensions set to 1. For example, the 4th array element of a 1-dimensional array, A(4), is stored as array element A(4,1,1). - - Arrays adhere to standard FORTRAN conventions. - - If the parameter name ``Par`` is input in a numeric argument of a command, the numeric value of the parameter (as assigned with :ref:`starset`, :ref:`get`, =, etc.) is substituted into the command at that point. Substitution occurs only if the parameter name is used between blanks, commas, parentheses, or arithmetic operators (or any combination) in a numeric argument. Substitution can be prevented by enclosing the parameter name ``Par`` within single quotes ( ' ), if the parameter is alone in the argument; if the parameter is part of an arithmetic expression, the entire expression must be enclosed within single quotes to prevent substitution. In either case the character string will be used instead of the numeric value (and the string will be taken as 0.0 if it is in a numeric argument). - - A forced substitution is available in the text fields of :ref:`title`, :ref:`stitle`, :ref:`tlabel`, :ref:`an3d`, :ref:`syp` ( ``ARG1`` -- ``ARG8`` ), and :ref:`abbr` by enclosing the parameter within percent (%) signs. Also, parameter substitution can be forced within the file name or extension fields of commands having these fields by enclosing the parameter within percent (%) signs. Array parameters ( :ref:`dim` ) must include a subscript (within parentheses) to identify the array element whose value is to be substituted, such as A(1,3). Out-of-range subscripts result in an error message. Non-integer subscripts are allowed when identifying a TABLE array element for substitution. A proportional linear interpolation of values among the nearest array elements is performed before substitution. Interpolation is done in all three dimensions. - - Interpolation is based upon the assigned index numbers which must be defined when the table is filled ( :ref:`dim` ). - - Most alphanumeric arguments permit the use of character parameter substitution. When the parameter name ``Par`` input, the alphanumeric value of the parameter is substituted into the command at that point. Substitution can be suppressed by enclosing the parameter name within single quotes ( ' ). Forced substitution is available in some fields by enclosing the parameter name within percent (%) signs. Valid forced substitution fields include command name fields, ``Fname`` (filename) or ``Ext`` (extension) arguments, :ref:`abbr` command ( ``Abbr`` arguments), :ref:`title` and :ref:`stitle` commands ( ``Title`` argument) and :ref:`tlabel` command ( ``Text`` argument). Character parameter substitution is also available in the :ref:`ask`, :ref:`an3d`, :ref:`cfwrite`, :ref:`if`, :ref:`elseif`, :ref:`msg`, :ref:`starset`, :ref:`use`, :ref:`vread`, and :ref:`vwrite` commands. Character array parameters must include a subscript (within parentheses) to identify the array element whose value is to be substituted. - - If a parameter `operation expression` is input in a numeric argument, the numeric value of the expression is substituted into the command at that point. Allowable operation expressions are of the form E1oE2oE3 ...oE10 - - where E1, E2, etc. are expressions connected by operators (o). The allowable operations (o) are + - * / \*\* < > - - For example, A+B\*\*C/D\*E is a valid operation expression. The * represents multiplication and the \*\* represents exponentiation. - - Exponentiation of a negative number (without parentheses) to an integer power follows standard FORTRAN hierarchy conventions; that is, the positive number is exponentiated and then the sign is attached. Thus, -4\*\*2 is evaluated as -16. If parentheses are applied, such as (-4)\*\*2, the result is 16. - - A parameter is evaluated as a number within parentheses before exponentiation. Exponentiation of a negative number to a non-integer power is performed by exponentiating the positive number and prepending the minus sign, for example, -4\*\*2.3 is -(4\*\*2.3). The < and > operators allow conditional substitution. For example, E1 For example, + A+B\*\*C/D\*E is a valid operation expression. The * represents multiplication and the \*\* represents + exponentiation. Exponentiation of a negative number (without parentheses) to an integer power + follows standard FORTRAN hierarchy conventions; that is, the positive number is exponentiated and + then the sign is attached. Thus, -4\*\*2 is evaluated as -16. If parentheses are applied, such as + (-4)\*\*2, the result is 16. A parameter is evaluated as a number within parentheses before + exponentiation. Exponentiation of a negative number to a non-integer power is performed by + exponentiating the positive number and prepending the minus sign, for example, -4\*\*2.3 is -(4\*\*2.3). + The < and > operators allow conditional substitution. For example, E1`_ + + Parameters + ---------- + par : str + Table array parameter name as defined by the :ref:`dim` command. + + fname : str + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. File name has no default. + + ext : str + Filename extension (eight-character maximum). Extension has no default. + + nskip : str + Number of comment lines at the beginning of the file being read that will be skipped during the + reading. Default = 0. + + Notes + ----- + Use this command to read in a table of data from an external file into a table array parameter. The + external file may be created using a text editor or by an external application or program. To be + used by :ref:`tread`, the external file's encoding format must be UTF-8, and the file must be in + tab-delimited, blank-delimited, or comma-delimited format. The TABLE type array parameter must be + defined before you can read in an external file. See :ref:`dim` for more information. This command + is not applicable to 4- or 5-D tables. + """ + command = f"*TREAD,{par},{fname},{ext},{nskip}" + return self.run(command, **kwargs) + def taxis( self, - parmloc="", - naxis="", - val1="", - val2="", - val3="", - val4="", - val5="", - val6="", - val7="", - val8="", - val9="", - val10="", + parmloc: str = "", + naxis: str = "", + val1: str = "", + val2: str = "", + val3: str = "", + val4: str = "", + val5: str = "", + val6: str = "", + val7: str = "", + val8: str = "", + val9: str = "", + val10: str = "", **kwargs, ): r"""Defines table index numbers. @@ -740,29 +619,67 @@ def taxis( ---------- parmloc : str Name and starting location in the table array parameter for indexing. Indexing occurs along the - axis defined with ``nAxis`` . + axis defined with ``nAxis``. naxis : str Axis along which indexing occurs. Valid labels are: - * ``1`` - Corresponds to Row. Default. + * ``1`` - Corresponds to Row. Default. + * ``2`` - Corresponds to Column. + * ``3`` - Corresponds to Plane. + * ``4`` - Corresponds to Book. + * ``5`` - Corresponds to Shelf. + * ``ALL`` - Lists all index numbers. Valid only if ``Val1`` = LIST. - * ``2`` - Corresponds to Column. + val1 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - * ``3`` - Corresponds to Plane. + val2 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - * ``4`` - Corresponds to Book. + val3 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - * ``5`` - Corresponds to Shelf. + val4 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - * ``ALL`` - Lists all index numbers. Valid only if ``Val1`` = LIST. + val5 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - val1, val2, val3, . . ., val10 : str + val6 : str Values of the index numbers for the axis ``nAxis``, starting from the table array parameter - location ``ParmLoc`` . You can define up to ten values. + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. - To list the index values specified with ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, - ``Val2`` - ``Val10`` are ignored. + val7 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. + + val8 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. + + val9 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. + + val10 : str + Values of the index numbers for the axis ``nAxis``, starting from the table array parameter + location ``ParmLoc``. You can define up to ten values. To list the index values specified with + ``nAxis``, issue ``Val1`` = LIST. If ``Val1`` = LIST, ``Val2`` - ``Val10`` are ignored. Notes ----- @@ -778,167 +695,107 @@ def taxis( command = f"*TAXIS,{parmloc},{naxis},{val1},{val2},{val3},{val4},{val5},{val6},{val7},{val8},{val9},{val10}" return self.run(command, **kwargs) - def tread(self, par="", nskip="", **kwargs): - r"""Reads data from an external file into a table array parameter. + def vread( + self, + parr: str = "", + fname: str = "", + ext: str = "", + label: str = "", + n1: str = "", + n2: str = "", + n3: str = "", + nskip: str = "", + **kwargs, + ): + r"""Reads data and produces an array parameter vector or matrix. - Mechanical APDL Command: `\*TREAD `_ + Mechanical APDL Command: `\*VREAD `_ Parameters ---------- - par : str - Table array parameter name as defined by the :ref:`dim` command. + parr : str + The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. The + parameter must exist as a dimensioned array ( :ref:`dim` ). String arrays are limited to a + maximum of 8 characters. fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - File name has no default. + File name and directory path (248 characters maximum, including the characters needed for the + directory path). An unspecified directory path defaults to the working directory; in this case, you + can use all 248 characters for the file name. If the ``Fname`` field is left blank, reading continues from the current input + device, such as the terminal. ext : str Filename extension (eight-character maximum). - Extension has no default. + + label : str + Can take a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (IJK). + + n1 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. + + n2 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. + + n3 : str + Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and + ``n3`` default to 1. nskip : str - Number of comment lines at the beginning of the file being read that will be skipped during the - reading. Default = 0. + Number of lines at the beginning of the file being read that will be skipped during the reading. + Default = 0. Notes ----- - Use this command to read in a table of data from an external file into a table array parameter. The external file may be created using a text editor or by an external application or program. To be used by :ref:`tread`, the external file's encoding format must be UTF-8, and the file must be in tab-delimited, blank-delimited, or comma-delimited format. The TABLE type array parameter must be defined before you can read in an external file. See :ref:`dim` for more information. + Reads data from a file and fills in an array parameter vector or matrix. Data are read from a + formatted file or, if the menu is off ( :ref:`menu` ,OFF) and ``Fname`` is blank, from the next input lines. The format of the data to be read must be input immediately following the :ref:`vread` command. The format specifies the number of fields to be read per record, the field width, and the placement of the decimal point (if none specified in the value). The read operation follows the available FORTRAN FORMAT conventions of the system (see your system FORTRAN manual). Any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) or alphanumeric format (A) may be used. Alphanumeric + strings are limited to a maximum of 8 characters for any field (A8). For storage of string arrays + greater than 8 characters, the \*SREAD command can be used. Integer (I) and list-directed (\*) + descriptors may `not` be used. `The parentheses must be included in the format` and the format must not exceed 80 characters (including parentheses). The input line length is + limited to 128 characters. - This command is not applicable to 4- or 5-D tables. - """ - command = f"*TREAD,{par},{nskip}" - return self.run(command, **kwargs) + A starting array element number must be defined for the result array parameter vector (numeric or + character). For example, entering these two lines: - def vfill( - self, - parr="", - func="", - con1="", - con2="", - con3="", - con4="", - con5="", - con6="", - con7="", - con8="", - con9="", - con10="", - **kwargs, - ): - r"""Fills an array parameter. + .. code:: - Mechanical APDL Command: `\*VFILL `_ + \*VREAD,A(1),ARRAYVAL + (2F6.0) - Parameters - ---------- - parr : str - The name of the resulting numeric array parameter vector. See :ref:`starset` for name - restrictions. + will read two values from each line of file ARRAYVAL and assign the values to A(1), A(2), A(3), etc. + Reading continues until successive row elements ( :ref:`vlen`, :ref:`vmask`, :ref:`dim` ) are filled. - func : str - Fill function: + For an array parameter matrix, a starting array element row and column number must be defined. For + example, entering these two lines: - * ``DATA`` - Assign specified values ``CON1``, ``CON2``, etc. to successive array - elements. Up - to 10 assignments may be made at a time. Any `CON` values after a blank `CON` value are - ignored. - - * ``RAMP`` - Assign ramp function values: ``CON1`` +((n-1)\* ``CON2`` ), where n is the loop - number ( :ref:`vlen` ). To specify a constant function (no ramp), set ``CON2`` to zero. - - * ``RAND`` - Assign random number values based on a uniform distribution RAND( ``CON1``, - ``CON2`` ), where: - - ``CON1`` is the lower bound (defaults to 0.0) - ``CON2`` is the upper bound (defaults to 1.0) - - * ``GDIS`` - Assign random sample of Gaussian distributions GDIS( ``CON1``, ``CON2`` ) - where: - - ``CON1`` is the mean (defaults to 0.0) - ``CON2`` is the standard deviation (defaults to 1.0) - - * ``TRIA`` - Assigns random number values based on a triangular distribution TRIA( ``CON1`` - , - ``CON2``, ``CON3`` ) where: - - ``CON1`` is the lower bound (defaults to 0.0) - ``CON2`` is the location of the peak value ( ``CON1`` ≤ ``CON2`` ≤ ``CON3`` ; ``CON2`` - defaults - to 0 - if ``CON1`` ≤ 0 ≤ ``CON3``, ``CON1`` if 0 ≤ ``CON1``, or ``CON3`` if ``CON3`` ≤ 0) - ``CON3`` is the upper bound (defaults to 1.0 + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ - 0) - - * ``BETA`` - Assigns random number values based on a beta distribution BETA( ``CON1``, - ``CON2`` - , ``CON3``, ``CON4`` ) where: - - ``CON1`` is the lower bound (defaults to 0.0) - ``CON2`` is the upper bound (defaults to 1.0 + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ - 0) - ``CON3`` and ``CON4`` are the alpha and beta parameters, respectively, of the beta function. - - Alpha - and beta must both be positive; they default to 1.0. - - * ``GAMM`` - Assigns random number values based on a gamma distribution: GAMM( ``CON1``, - ``CON2``, ``CON3`` ) where: - - ``CON1`` is the lower bound (defaults to 0.0) - ``CON2`` and ``CON3`` are the alpha and beta parameters, respectively, of the gamma - function. - Alpha - and beta must both be positive; they default to 1.0. - - * ``RIGID`` - Generates the rigid body modes with respect to the reference point coordinates - ( - ``CON1``, ``CON2``, ``CON3`` ). The dimensions of the array parameter ``ParR`` are (dim 1 - ,dim 2 - ) where dim 1 is the maximum node number (including internal nodes but excluding orientation - nodes ) multiplied by the number of degrees of freedom, and dim 2 is the number of rigid body - modes (which corresponds to the number of structural degrees of freedom). - - * ``CLUSTER`` - Generates excitation frequencies with clustering option CLUSTER( ``CON1``, - ``CON2``, ``CON3``, ``CON4``, ``%CON5%`` ) where: - - ``CON1`` is the lower end of the frequency range in Hz (0 < ``CON1`` ) - ``CON2`` is the upper end of the frequency range in Hz ( ``CON1`` < ``CON2`` ) - ``CON3`` is the number of points on each side of the natural frequency (4 ≤ ``CON3`` ≤ 20, - defaults - to 4) - ``CON4`` is the constant damping ratio value or an array parameter (size NFR) specifying the - - damping - ratios (if zero or blank, defaults to constant damping ratio of 0.005) - ``CON5`` is an array parameter (size NFR) specifying the natural frequencies in Hz - The dimension of the resulting array parameter ParR is less than 2+NFR\*(2\* - ``CON3`` +1) where NFR is the number of natural frequencies defined in ``CON5`` . - - con1, con2, con3, . . ., con10 : str - Constants used with above functions. + .. code:: - Notes - ----- - Operates on input data and produces one output array parameter vector according to: ``ParR`` = f( ``CON1``, ``CON2``, ...) + \*VREAD,A(1,1),ARRAYVAL,,,IJK,10,2 + (2F6.0) + + will read two values from each line of file ARRAYVAL and assign the values to A(1,1), A(2,1), + A(3,1), etc. Reading continues until ``n1`` (10) successive row elements are filled. Once the maximum row number is reached, subsequent data will be read into the next column (for example, A(1,2), A(2,2), A(3,2), etc.) + + For numerical parameters, absolute values and scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. If you are in the GUI the :ref:`vread` command must be contained in an externally prepared file read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). - where the functions (f) are described above. Operations use successive array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. For example, :ref:`vfill` ,A,RAMP,1,10 assigns A(1) = 1.0, A(2) = 11.0, A(3) = 21.0, etc. :ref:`vfill` ,B(5,1),DATA,1.5,3.0 assigns B(5,1) = 1.5 and B(6,1) = 3.0. Absolute values and scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. + This command is not applicable to 4- or 5-D arrays. This command is valid in any processor. """ - command = f"*VFILL,{parr},{func},{con1},{con2},{con3},{con4},{con5},{con6},{con7},{con8},{con9},{con10}" + command = f"*VREAD,{parr},{fname},{ext},{label},{n1},{n2},{n3},{nskip}" return self.run(command, **kwargs) def starvget( self, - parr="", - entity="", - entnum="", - item1="", - it1num="", - item2="", - it2num="", - kloop="", + parr: str = "", + entity: str = "", + entnum: str = "", + item1: str = "", + it1num: str = "", + item2: str = "", + it2num: str = "", + kloop: str = "", **kwargs, ): r"""Retrieves values and stores them into an array parameter. @@ -964,108 +821,407 @@ def starvget( it1num : str The number (or label) for the specified ``Item1`` (if any). Valid ``IT1NUM`` values are as shown - in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an + in the ``IT1NUM`` columns of the tables below. Some ``Item1`` labels do not require an ``IT1NUM`` value. - item2, it2num : str + item2 : str + A second set of item labels and numbers to further qualify the item for which data is to be + retrieved. Most items do not require this level of information. + + it2num : str A second set of item labels and numbers to further qualify the item for which data is to be retrieved. Most items do not require this level of information. kloop : str Field to be looped on: - * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). + * ``0 or 2`` - Loop on the ``ENTNUM`` field (default). + * ``3`` - Loop on the ``Item1`` field. + * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM``. + * ``5`` - Loop on the ``Item2`` field. + * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM``. + + Notes + ----- + Retrieves values for specified items and stores the values in an output vector of a user-named array + parameter according to: ``ParR`` = f( ``Entity``, ``ENTNUM``, ``Item1``, ``IT1NUM``, ``Item2`` , + ``IT2NUM`` ) where (f) is the :ref:`get` function; ``Entity``, ``Item1``, and ``Item2`` are + keywords; and ``ENTNUM``, ``IT1NUM``, and ``IT2NUM`` are numbers or labels corresponding to the + keywords. Looping continues over successive entity numbers ( ``ENTNUM`` ) for the ``KLOOP`` default. + For example, :ref:`starvget` ,A(1),ELEM,5,CENT,X returns the centroid x-location of element 5 and + stores the result in the first location of A. Retrieving continues with element 6, 7, 8, etc., + regardless of whether the element exists or is selected, until successive array locations are + filled. Use :ref:`vlen` or :ref:`vmask` to skip locations. Absolute values and scale factors may be + applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( + :ref:`vcum` ). See the :ref:`voper` command for general details. Results can be put back into an + analysis by writing a file of the desired input commands with the :ref:`vwrite` command. See also + the :ref:`starvput` command. Both :ref:`get` and :ref:`starvget` retrieve information from the + active data stored in memory. The database is often the source, and sometimes the information is + retrieved from common memory blocks that Mechanical APDL uses to manipulate information. Although POST1 and + POST26 operations use a ``\*.rst`` file, GET data is accessed from the database or from the common + blocks. Get operations do not access the ``\*.rst`` file directly. The :ref:`starvget` command + retrieves both the unprocessed real and the imaginary parts (original and duplicate sector nodes and + elements) of a `cyclic symmetry + `_ solution. + Each of the sections for accessing \*VGET parameters are shown in the following order: `\*VGET + PREP7 Items + `_ + `\*VGET POST1 Items + `_ + This command is valid in any processor. + """ + command = ( + f"*VGET,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" + ) + return self.run(command, **kwargs) - * ``3`` - Loop on the ``Item1`` field. + def vfill( + self, + parr: str = "", + func: str = "", + con1: str = "", + con2: str = "", + con3: str = "", + con4: str = "", + con5: str = "", + con6: str = "", + con7: str = "", + con8: str = "", + con9: str = "", + con10: str = "", + **kwargs, + ): + r"""Fills an array parameter. - * ``4`` - Loop on the ``IT1NUM`` field. Successive items are as shown with ``IT1NUM`` . + Mechanical APDL Command: `\*VFILL `_ - * ``5`` - Loop on the ``Item2`` field. + Parameters + ---------- + parr : str + The name of the resulting numeric array parameter vector. See :ref:`starset` for name + restrictions. - * ``6`` - Loop on the ``IT2NUM`` field. Successive items are as shown with ``IT2NUM`` . + func : str + Fill function: + + * ``DATA`` - Assign specified values ``CON1``, ``CON2``, etc. to successive array elements. Up to + 10 assignments may be made at a time. Any `CON` values after a blank `CON` value are ignored. + * ``RAMP`` - Assign ramp function values: ``CON1`` +((n-1)\* ``CON2`` ), where n is the loop number ( + :ref:`vlen` ). To specify a constant function (no ramp), set ``CON2`` to zero. + * ``RAND`` - Assign random number values based on a uniform distribution RAND( ``CON1``, ``CON2`` + ), where: ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the upper bound (defaults to + 1.0) + * ``GDIS`` - Assign random sample of Gaussian distributions GDIS( ``CON1``, ``CON2`` ) where: + ``CON1`` is the mean (defaults to 0.0) ``CON2`` is the standard deviation (defaults to 1.0) + * ``TRIA`` - Assigns random number values based on a triangular distribution TRIA( ``CON1`` , + ``CON2``, ``CON3`` ) where: ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the + location of the peak value ( ``CON1`` ≤ ``CON2`` ≤ ``CON3`` ; ``CON2`` defaults to 0 if ``CON1`` ≤ + 0 ≤ ``CON3``, ``CON1`` if 0 ≤ ``CON1``, or ``CON3`` if ``CON3`` ≤ 0) ``CON3`` is the upper bound + (defaults to 1.0 + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ 0) + * ``BETA`` - Assigns random number values based on a beta distribution BETA( ``CON1``, ``CON2`` , + ``CON3``, ``CON4`` ) where: ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` is the upper + bound (defaults to 1.0 + ``CON1`` if ``CON1`` ≥ 0 or 0.0 if ``CON1`` ≤ 0) ``CON3`` and ``CON4`` + are the alpha and beta parameters, respectively, of the beta function. Alpha and beta must both be + positive; they default to 1.0. + * ``GAMM`` - Assigns random number values based on a gamma distribution: GAMM( ``CON1``, ``CON2`` , + ``CON3`` ) where: ``CON1`` is the lower bound (defaults to 0.0) ``CON2`` and ``CON3`` are the + alpha and beta parameters, respectively, of the gamma function. Alpha and beta must both be + positive; they default to 1.0. + * ``RIGID`` - Generates the rigid body modes with respect to the reference point coordinates ( + ``CON1``, ``CON2``, ``CON3`` ). The dimensions of the array parameter ``ParR`` are (dim 1 ,dim 2 + ) where dim 1 is the maximum node number (including internal nodes but excluding orientation nodes + ) multiplied by the number of degrees of freedom, and dim 2 is the number of rigid body modes + (which corresponds to the number of structural degrees of freedom). + * ``CLUSTER`` - Generates excitation frequencies with clustering option CLUSTER( ``CON1``, ``CON2`` + , ``CON3``, ``CON4``, ``%CON5%`` ) where: ``CON1`` is the lower end of the frequency range in + Hz (0 < ``CON1`` ) ``CON2`` is the upper end of the frequency range in Hz ( ``CON1`` < ``CON2`` ) + ``CON3`` is the number of points on each side of the natural frequency (4 ≤ ``CON3`` ≤ 20, + defaults to 4) ``CON4`` is the constant damping ratio value or an array parameter (size NFR) + specifying the damping ratios (if zero or blank, defaults to constant damping ratio of 0.005) + ``CON5`` is an array parameter (size NFR) specifying the natural frequencies in Hz The dimension + of the resulting array parameter ParR is less than 2+NFR\*(2\* ``CON3`` +1) where NFR is the number + of natural frequencies defined in ``CON5``. + + con1 : str + Constants used with above functions. + + con2 : str + Constants used with above functions. + + con3 : str + Constants used with above functions. + + con4 : str + Constants used with above functions. + + con5 : str + Constants used with above functions. + + con6 : str + Constants used with above functions. + + con7 : str + Constants used with above functions. + + con8 : str + Constants used with above functions. + + con9 : str + Constants used with above functions. + + con10 : str + Constants used with above functions. Notes ----- - Retrieves values for specified items and stores the values in an output vector of a user-named array parameter according to: ``ParR`` = f( ``Entity``, ``ENTNUM``, ``Item1``, ``IT1NUM``, ``Item2``, ``IT2NUM`` ) + Operates on input data and produces one output array parameter vector according to: ``ParR`` = f( + ``CON1``, ``CON2`` ,...) where the functions (f) are described above. Operations use successive + array elements ( :ref:`vlen`, :ref:`vmask` ) with the default being all successive elements. For + example, :ref:`vfill` ,A,RAMP,1,10 assigns A(1) = 1.0, A(2) = 11.0, A(3) = 21.0, etc. :ref:`vfill` + ,B(5,1),DATA,1.5,3.0 assigns B(5,1) = 1.5 and B(6,1) = 3.0. Absolute values and scale factors may be + applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( + :ref:`vcum` ). See the :ref:`voper` command for details. This command is valid in any processor. + """ + command = f"*VFILL,{parr},{func},{con1},{con2},{con3},{con4},{con5},{con6},{con7},{con8},{con9},{con10}" + return self.run(command, **kwargs) - where (f) is the :ref:`get` function; ``Entity``, ``Item1``, and ``Item2`` are keywords; and ``ENTNUM``, ``IT1NUM``, and ``IT2NUM`` are numbers or labels corresponding to the keywords. Looping continues over successive entity numbers ( ``ENTNUM`` ) for the ``KLOOP`` default. For example, :ref:`starvget` ,A(1),ELEM,5,CENT,X returns the centroid x-location of element 5 and stores the result in the first location of A. Retrieving continues with element 6, 7, 8, etc., regardless of whether the element exists or is selected, until successive array locations are filled. Use :ref:`vlen` or :ref:`vmask` to skip locations. Absolute values and scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for general details. Results can be put back into an analysis by writing a file of the desired input commands with the :ref:`vwrite` command. See also the :ref:`starvput` command. + def ask(self, par: str = "", query: str = "", dval: str = "", **kwargs): + r"""Prompts the user to input a parameter value. - Both :ref:`get` and :ref:`starvget` retrieve information from the active data stored in memory. The database is often the source, and sometimes the information is retrieved from common memory blocks that Mechanical APDL uses to manipulate information. Although POST1 and POST26 operations use a ``\*.rst`` file, GET data is accessed from the database or from the common blocks. Get operations do not access the ``\*.rst`` file directly. + Mechanical APDL Command: `\*ASK `_ - The :ref:`starvget` command retrieves both the unprocessed real and the imaginary parts (original and duplicate sector nodes and elements) of a `cyclic symmetry `_ solution. + Parameters + ---------- + par : str + An alphanumeric name used to identify the scalar parameter. See :ref:`starset` for name + restrictions. - Each of the sections for accessing \*VGET parameters are shown in the following order: + query : str + Text string to be displayed on the next line as the query (32 characters maximum). Characters + having special meaning (such as $ ! ) should not be included. - `\*VGET PREP7 Items - `_ + dval : str + Default value assigned to the parameter if the user issues a blank response. May be a number or + character string (up to 8 characters enclosed in single quotes). If a default is not assigned, a + blank response will delete the parameter. - `\*VGET POST1 Items - `_ + Notes + ----- + Intended primarily for use in macros, the command prints the query (after the word ``ENTER`` ) on + the next line and waits for a response. The response is read from the keyboard, except in batch mode + ( :ref:`batch` ), when the response(s) must be the next-read input line(s). The response may be a + number, a character string (up to 8 characters enclosed in single quotes), a parameter (numeric or + character) or an expression that evaluates to a number. The scalar parameter is then set to the + response value. For example, :ref:`ask` ,NN,PARAMETER NN will set NN to the value entered on the + next line (after the prompt ``ENTER PARAMETER NN`` ). The :ref:`ask` command is not written to + ``File.LOG``, but the responses are written there as follows: If :ref:`ask` is contained in a + macro, the response(s) (only) is written to ``File.LOG`` on the line(s) following the macro name. If + not contained in a macro, the response is written to ``File.LOG`` as a parameter assignment (that + is, ``Par`` = "user-response"). If used within a do-loop that is executed interactively, :ref:`ask` + should be contained in a macro. If not contained in a macro, :ref:`ask` will still query the user as + intended, but the resulting log file will `not` reproduce the effects of the original run. This + command is valid in any processor. + """ + command = f"*ASK,{par},{query},{dval}" + return self.run(command, **kwargs) - This command is valid in any processor. + def afun(self, lab: str = "", **kwargs): + r"""Specifies units for angular functions in parameter expressions. + + Mechanical APDL Command: `\*AFUN `_ + + Parameters + ---------- + lab : str + Specifies the units to be used: + + * ``RAD`` - Use radians for input and output of parameter angular functions (default). + * ``DEG`` - Use degrees for input and output of parameter angular functions. + * ``STAT`` - Show current setting (DEG or RAD) for this command. + + Notes + ----- + Only the SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2, ANGLEK, and ANGLEN functions ( :ref:`starset` , + :ref:`vfun` ) are affected by this command. """ - command = ( - f"*VGET,{parr},{entity},{entnum},{item1},{it1num},{item2},{it2num},{kloop}" - ) + command = f"*AFUN,{lab}" return self.run(command, **kwargs) - def vread(self, parr="", label="", n1="", n2="", n3="", nskip="", **kwargs): - r"""Reads data and produces an array parameter vector or matrix. + def dim( + self, + par: str = "", + type_: str = "", + imax: str = "", + jmax: str = "", + kmax: str = "", + var1: str = "", + var2: str = "", + var3: str = "", + csysid: str = "", + **kwargs, + ): + r"""Defines an array parameter and its dimensions. - Mechanical APDL Command: `\*VREAD `_ + Mechanical APDL Command: `\*DIM `_ Parameters ---------- - parr : str - The name of the resulting array parameter vector. See :ref:`starset` for name restrictions. The - parameter must exist as a dimensioned array ( :ref:`dim` ). String arrays are limited to a - maximum of 8 characters. + par : str + Name of parameter to be dimensioned. See :ref:`starset` for name restrictions. - fname : str - File name and directory path (248 characters maximum, including the characters needed for the directory path). An unspecified directory path defaults to the working directory; in this case, you can use all 248 characters for the file name. - If the ``Fname`` field is left blank, reading continues from the current input device, such as - the terminal. + type : str + Array type: - ext : str - Filename extension (eight-character maximum). - label : str - Can take a value of IJK, IKJ, JIK, JKI, KIJ, KJI, or blank (IJK). + * ``ARRAY`` - Arrays are similar to standard FORTRAN arrays (indices are integers) (default). Index + numbers for the rows, columns, and planes are sequential values beginning with one. Used for 1-, + 2-, or 3D arrays. + * ``ARR4`` - Same as ARRAY, but used to specify 4-D arrays. + * ``ARR5`` - Same as ARRAY, but used to specify 5-D arrays. + * ``CHAR`` - Array entries are character strings (up to 8 characters each). Index numbers for rows, + columns, and planes are sequential values beginning with one. + * ``TABLE`` - Array indices are real (non-integer) numbers which must be defined when filling the + table. Index numbers for the rows and columns are stored in the zero column and row "array + elements" and are initially assigned a near-zero value. Index numbers must be in ascending order + and are used only for retrieving an array element. When retrieving an array element with a real + index that does not match a specified index, linear interpolation is done among the nearest + indices and the corresponding array element values ( :ref:`starset` ). Used for 1-, 2-, or 3D + tables. + * ``TAB4`` - Same as TABLE, but used to specify 4-D tables. + * ``TAB5`` - Same as TABLE, but used to specify 5-D tables. + * ``STRING`` - Array entries are character strings (up to IMAX each). Index numbers for columns and + planes are sequential values beginning with 1. Row index is character position in string. - n1, n2, n3 : str - Read as ((( ``ParR`` (i,j,k), k = 1,n1), i = 1, n2), j = 1, n3) for ``Label`` = KIJ. ``n2`` and - ``n3`` default to 1. + imax : str + Extent of first dimension (row). (For ``Type`` = STRING, ``IMAX`` is rounded up to the next + multiple of eight and has a limit of 248). Default = 1. - nskip : str - Number of lines at the beginning of the file being read that will be skipped during the reading. - Default = 0. + jmax : str + Extent of second dimension (column). Default = 1. + + kmax : str + Extent of third dimension (plane). Default = 1. + + var1 : str + Variable name corresponding to the first dimension (row) for ``Type`` = TABLE, TAB4, or TAB5. + Default = Row. + + var2 : str + Variable name corresponding to the second dimension (column) for ``Type`` = TABLE, TAB4, or + TAB5. Default = Column. + + var3 : str + Variable name corresponding to the third dimension (plane) for ``Type`` = TABLE, TAB4, TAB5. + Default = Plane. + + csysid : str + An integer corresponding to the coordinate system ID number. Default = 0 (global Cartesian). Notes ----- - Reads data from a file and fills in an array parameter vector or matrix. Data are read from a formatted file or, if the menu is off ( :ref:`menu` ,OFF) and ``Fname`` is blank, from the next input lines. The format of the data to be read must be input immediately following the :ref:`vread` command. The format specifies the number of fields to be read per record, the field width, and the placement of the decimal point (if none specified in the value). The read operation follows the available FORTRAN FORMAT conventions of the system (see your system FORTRAN manual). Any standard FORTRAN `real` format (such as (4F6.0), (E10.3,2X,D8.2), etc.) or alphanumeric format (A) may be used. Alphanumeric strings are limited to a maximum of 8 characters for any field (A8). For storage of string arrays greater than 8 characters, the \*SREAD command can be used. Integer (I) and list-directed (\*) descriptors may `not` be used. `The parentheses must be included in the format` and the format must not exceed 80 characters (including parentheses). The input line length is limited to 128 characters. + Up to three dimensions (row, column, and plane) may be defined using ARRAY and TABLE. Use ARR4, + ARR5, TAB4, and TAB5 to define up to five dimensions (row, column, plane, book, and shelf). An index + number is associated with each row, column, and plane. For array and table type parameters, element + values are initialized to zero. For character and string parameters, element values are initialized + to (blank). A defined parameter must be deleted ( :ref:`starset` ) before its dimensions can be changed. Scalar (single valued) parameters should not be dimensioned. :ref:`dim` ,A,,3 defines a vector array with elements A(1), A(2), and A(3). :ref:`dim` ,B,,2,3 defines a 2x3 array with elements B(1,1), B(2,1), B(1,2), B(2,2), B(1,3), and B(2,3). Use :ref:`starstatus`, ``Par`` to display elements of array ``Par`` . You can write formatted data files (tabular formatting) from data held in arrays through the :ref:`vwrite` command. - A starting array element number must be defined for the result array parameter vector (numeric or character). For example, entering these two lines: + If you use table parameters to define boundary conditions, then ``Var1``, ``Var2``, and/or ``Var3`` can either specify a primary variable (listed in ) or can be an independent parameter. If specifying an independent parameter, then you must define an additional table for the independent parameter. The additional table must have the same name as the independent parameter and may be a function of one or more primary variables or another independent parameter. All independent parameters must relate to a primary variable. - .. code:: + Tabular load arrays can be defined in both global Cartesian (default), cylindrical, spherical, or + local (see below) coordinate systems by specifying ``CSYSID``, as defined in :ref:`local` . Coordinate system ``CSYSID`` must exist prior to issuing the :ref:`dim` command. - \*VREAD,A(1),ARRAYVAL - (2F6.0) + The following constraints apply when specifying a local coordinate system for your tabular loads: - will read two values from each line of file ARRAYVAL and assign the values to A(1), A(2), A(3), etc. Reading continues until successive row elements ( :ref:`vlen`, :ref:`vmask`, :ref:`dim` ) are filled. + Only Cartesian, cylindrical and spherical coordinate systems are supported + Angle values for Y in cylindrical or spherical coordinate systems must be input in degrees and must + be positive values between 0 and 360 degrees (0 :math:`` Y :math:`` 360) + Angle values for Z in spherical coordinate system must be input in degrees and must be positive + values between -90 and +90 ( -90 :math:`` Z :math:`` 90) - For an array parameter matrix, a starting array element row and column number must be defined. For example, entering these two lines: + If specifying a 4- or 5-D array or table, four additional fields ( ``LMAX``, ``MMAX``, ``Var4``, and ``Var5`` ) are available. Thus, for a 4-D table, the command syntax would be: .. code:: - \*VREAD,A(1,1),ARRAYVAL,,,IJK,10,2 - (2F6.0) + \*DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,Var1,Var2,Var3,Var4,CSYSID - will read two values from each line of file ARRAYVAL and assign the values to A(1,1), A(2,1), A(3,1), etc. Reading continues until ``n1`` (10) successive row elements are filled. Once the maximum row number is reached, subsequent data will be read into the next column (for example, A(1,2), A(2,2), A(3,2), etc.) + For a 5-D table, the command syntax is: - For numerical parameters, absolute values and scale factors may be applied to the result parameter ( :ref:`vabs`, :ref:`vfact` ). Results may be cumulative ( :ref:`vcum` ). See the :ref:`voper` command for details. If you are in the GUI the :ref:`vread` command must be contained in an externally prepared file read into Mechanical APDL (that is, :ref:`use`, :ref:`input`, etc.). + .. code:: - This command is not applicable to 4- or 5-D arrays. + \*DIM,Par,Type,IMAX,JMAX,KMAX,LMAX,MMAX,Var1,Var2,Var3,Var4,Var5,CSYSID + + You cannot create or edit 4- or 5-D arrays or tables via the GUI. + + For more information, see `Array Parameters `_ + + **\*DIM - Primary Variables** + + .. flat-table:: + :header-rows: 1 + + * - Primary Variable + - Label for ``Var1, Var2, Var3, Var4, Var5`` + * - Time + - TIME + * - Frequency + - FREQ + * - X-coordinate location + - X + * - Y-coordinate location + - Y + * - Z-coordinate location + - Z + * - Temperature + - TEMP + * - Velocity + - VELOCITY + * - Pressure + - PRESSURE [ ] + * - Geometric gap/penetration + - GAP + * - Cyclic sector number + - SECTOR + * - Amplitude of the rotational velocity vector + - OMEGS + * - Eccentricity + - ECCENT + * - Phase shift + - THETA + * - Element number + - ELEM + * - Node number + - NODE + * - Concentration + - CONC + + Specify PRESSURE as the independent variable (not PRES). + + The X, Y, and Z coordinate locations listed above are valid in global Cartesian, or local + (Cartesian, cylindrical and spherical) coordinate systems. The VELOCITY label is applicable only to + the calculated fluid velocity in element FLUID116 . + + When using PRESSURE as a primary variable, the underlying element must have the pressure DOF + associated with it, or it must be a supported contact element. + + The gap/penetration label (GAP) is only used for defining certain contact element real constants. + + The frequency label (FREQ) is valid for harmonic analyses only. + + The node and element labels (NODE and ELEM) allow you to use node and element numbers as primary + variables, and their axis values should be integers. + + The OMEGS, ECCENT, and THETA primary variables only apply to the COMBI214 element. The amplitude of the rotational velocity (OMEGS) is an absolute value, so only positive + values of OMEGS are valid. The eccentricity (ECCENT) and phase shift (THETA) labels are only valid + for nonlinear analyses. + + If you use table parameters to define boundary conditions, the table names ( ``Par`` ) must not exceed 32 characters. + + In thermal analyses, if you apply tabular loads as a function of temperature but the rest of the + model is linear (for example, includes no temperature-dependent material properties or radiation ), + you should turn on Newton-Raphson iterations ( :ref:`nropt` ,FULL) to evaluate the temperature-dependent tabular boundary conditions correctly. This command is valid in any processor. """ - command = f"*VREAD,{parr},{label},{n1},{n2},{n3},{nskip}" + command = ( + f"*DIM,{par},{type_},{imax},{jmax},{kmax},{var1},{var2},{var3},{csysid}" + ) return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/process_controls.py b/src/ansys/mapdl/core/_commands/apdl/process_controls.py index 2b194d3ff6..bdc7622846 100644 --- a/src/ansys/mapdl/core/_commands/apdl/process_controls.py +++ b/src/ansys/mapdl/core/_commands/apdl/process_controls.py @@ -23,70 +23,94 @@ class ProcessControls: - def cycle(self, **kwargs): - r"""Bypasses commands within a do-loop. + def stargo(self, base: str = "", **kwargs): + r"""Causes a specified line on the input file to be read next. - Mechanical APDL Command: `\*CYCLE `_ + Mechanical APDL Command: `\*GO `_ + + Parameters + ---------- + base : str + "Go to" action: + + * ``:, label`` - A user-defined label (beginning with a colon (:), 8 characters maximum). The + command reader will skip (and wrap to the beginning of the file, if necessary) to the first line + that begins with the matching : ``label``. .. warning:: This label option may not be mixed + with do-loop or if-then-else constructs. + * ``STOP`` - This action will cause an exit from the Mechanical APDL program at this line. Notes ----- - Bypasses all commands between this command and the :ref:`enddo` command within a do-loop. The next loop (if applicable) is initiated. The cycle option may also be conditionally executed [Use the :ref:`if` ]. The :ref:`cycle` command must appear on the same file as the :ref:`do` command. - - This command is valid in any processor. + Causes the next read to be from a specified line on the input file. Lines may be skipped or reread. + The :ref:`stargo` command will `not` be executed unless it is part of a macro, user file (processed + by :ref:`use` ), an alternate input file (processed by :ref:`input` ), or unless it is used in a + batch-mode input stream. Jumping into, out of, or within a do-loop or an if-then-else construct to a + : ``label`` line is not allowed. This command is valid in any processor. """ - command = f"*CYCLE" + command = f"*GO,{base}" return self.run(command, **kwargs) - def do(self, par="", ival="", fval="", inc="", **kwargs): - r"""Defines the beginning of a do-loop. + def wait(self, dtime: str = "", **kwargs): + r"""Causes a delay before the reading of the next command. - Mechanical APDL Command: `\*DO `_ + Mechanical APDL Command: `/WAIT `_ Parameters ---------- - par : str - The name of the scalar parameter to be used as the loop index. See :ref:`starset` for name - restrictions. Any existing parameter of the same name will be redefined. There is no character - parameter substitution for the ``Par`` field. - - ival, fval, inc : str - Initially assign ``IVAL`` to ``Par`` . Increment ``IVAL`` by ``INC`` for each successive loop. - If ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults - to 1. Negative increments and non-integer numbers are allowed. + dtime : str + Time delay (in seconds). Maximum time delay is 59 seconds. Notes ----- - The block of commands following the :ref:`do` command (up to the :ref:`enddo` command) is executed repeatedly until some loop control is satisfied. Printout is automatically suppressed on all loops after the first (include a :ref:`gopr` command to restore the printout). The command line loop control ( ``Par``, ``IVAL``, ``FVAL``, ``INC`` ) must be input; however, a Use the :ref:`if` within the block can also be used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level of internal file switching is used for each nested :ref:`do` . Twenty levels of nested do-loops are allowed. + The command following the :ref:`wait` will not be processed until the specified wait time increment + has elapsed. Useful when reading from a prepared input file to cause a pause, for example, after a + display command so that the display can be reviewed for a period of time. Another "wait" feature is + available via the :ref:`ask` command. This command is valid in any processor. + """ + command = f"/WAIT,{dtime}" + return self.run(command, **kwargs) + + def cycle(self, **kwargs): + r"""Bypasses commands within a do-loop. - Do-loops that include :ref:`input`, :ref:`use`, or an "Unknown Command" macro, have less nesting available because each of these operations also uses a level of file switching. The :ref:`do`, :ref:`enddo`, and any :ref:`cycle` and :ref:`starexit` commands for a do-loop must all be read from the same file (or keyboard). You cannot use the `MULTIPRO `_ or :ref:`create` commands within a :ref:`do` -loop. Picking operations should also not be used within a :ref:`do` -loop. + Mechanical APDL Command: `\*CYCLE `_ - This command is valid in any processor. + Notes + ----- + Bypasses all commands between this command and the :ref:`enddo` command within a do-loop. The next + loop (if applicable) is initiated. The cycle option may also be conditionally executed [Use the + :ref:`if` ]. The :ref:`cycle` command must appear on the same file as the :ref:`do` command. This + command is valid in any processor. """ - command = f"*DO,{par},{ival},{fval},{inc}" + command = f"*CYCLE" return self.run(command, **kwargs) - def dowhile(self, par="", **kwargs): - r"""Loops repeatedly through the next :ref:`enddo` command. - - Mechanical APDL Command: `\*DOWHILE `_ + def endif(self, **kwargs): + r"""Ends an if-then-else. - Parameters - ---------- - par : str - The name of the scalar parameter to be used as the loop index. There is no character parameter - substitution for the ``Par`` field. + Mechanical APDL Command: `\*ENDIF `_ Notes ----- - :ref:`dowhile` loops repeatedly through the next :ref:`enddo` command as long as ``Par`` is greater than zero. The block of commands following the :ref:`dowhile` command (up to the :ref:`enddo` command) is executed repeatedly until some loop control is satisfied. Printout is automatically suppressed on all loops after the first (include a :ref:`gopr` command to restore the printout). The command line loop control ( ``Par`` ) must be input; however, :ref:`if` within the block can also be used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level of internal file switching is used for each nested :ref:`dowhile` . Twenty levels of nested do-loops are allowed. - - This command is valid in any processor. + Required terminator for the if-then-else construct. See :ref:`if` for details. If a batch input + stream hits an end-of-file during a false :ref:`if` condition, the analysis will not terminate + normally. You will need to terminate it externally (use either the Linux "kill" function or the + Windows task manager). The :ref:`endif` command must appear on the same file as the :ref:`if` + command, and all six characters must be input. This command is valid in any processor. """ - command = f"*DOWHILE,{par}" + command = f"*ENDIF" return self.run(command, **kwargs) def elseif( - self, val1="", oper1="", val2="", conj="", val3="", oper2="", val4="", **kwargs + self, + val1: str = "", + oper1: str = "", + val2: str = "", + conj: str = "", + val3: str = "", + oper2: str = "", + val4: str = "", + **kwargs, ): r"""Separates an intermediate if-then-else block. @@ -102,21 +126,14 @@ def elseif( oper1 : str Operation label. A tolerance of 1.0E-10 is used for comparisons between real numbers: - * ``EQ`` - Equal (for ``VAL1`` = ``VAL2`` ). - - * ``NE`` - Not equal (for ``VAL1`` ≠ ``VAL2`` ). - - * ``LT`` - Less than (for ``VAL1`` < ``VAL2`` ). - - * ``GT`` - Greater than (for ``VAL1`` > ``VAL2`` ). - - * ``LE`` - Less than or equal (for ``VAL1`` :math:`` #13 ``VAL2`` ). - - * ``GE`` - Greater than or equal (for ``VAL1`` :math:`` #13 ``VAL2`` ). - - * ``ABLT`` - Absolute values of ``VAL1`` and ``VAL2`` before < operation. - - * ``ABGT`` - Absolute values of ``VAL1`` and ``VAL2`` before > operation. + * ``EQ`` - Equal (for ``VAL1`` = ``VAL2`` ). + * ``NE`` - Not equal (for ``VAL1`` ≠ ``VAL2`` ). + * ``LT`` - Less than (for ``VAL1`` < ``VAL2`` ). + * ``GT`` - Greater than (for ``VAL1`` > ``VAL2`` ). + * ``LE`` - Less than or equal (for ``VAL1`` :math:`` ``VAL2`` ). + * ``GE`` - Greater than or equal (for ``VAL1`` :math:`` ``VAL2`` ). + * ``ABLT`` - Absolute values of ``VAL1`` and ``VAL2`` before < operation. + * ``ABGT`` - Absolute values of ``VAL1`` and ``VAL2`` before > operation. val2 : str Second numerical value (or parameter which evaluates to numerical value) in the conditional @@ -125,61 +142,31 @@ def elseif( conj : str (Optional) Connection between two logical clauses. - * ``AND -`` - True if both clauses ( ``Oper1`` and ``Oper2`` ) are true. - - * ``OR -`` - True if either clause is true. - - * ``XOR -`` - True if either (but not both) clause is true. + * ``AND -`` - True if both clauses ( ``Oper1`` and ``Oper2`` ) are true. + * ``OR -`` - True if either clause is true. + * ``XOR -`` - True if either (but not both) clause is true. val3 : str (Optional) Third numerical value (or parameter which evaluates to numerical value). oper2 : str (Optional) Operation label. This will have the same labels as ``Oper1``, except it uses - ``Val3`` and ``Val4`` . A tolerance of 1.0E-10 is used for comparisons between real numbers. + ``Val3`` and ``Val4``. A tolerance of 1.0E-10 is used for comparisons between real numbers. val4 : str (Optional) Fourth numerical value (or parameter value which evaluates to a numerical value). Notes ----- - Optional intermediate block separator within an if-then-else construct. All seven characters of the command name (\*ELSEIF) must be input. This command is similar to the :ref:`if` command except that the ``Base`` field is not used. The :ref:`if`, :ref:`elseif`, :ref:`else`, and :ref:`endif` commands for each if-then-else construct must all be read from the same file (or keyboard). - - This command is valid in any processor. + Optional intermediate block separator within an if-then-else construct. All seven characters of the + command name (\*ELSEIF) must be input. This command is similar to the :ref:`if` command except that + the ``Base`` field is not used. The :ref:`if`, :ref:`elseif`, :ref:`else`, and :ref:`endif` + commands for each if-then-else construct must all be read from the same file (or keyboard). This + command is valid in any processor. """ command = f"*ELSEIF,{val1},{oper1},{val2},{conj},{val3},{oper2},{val4}" return self.run(command, **kwargs) - def enddo(self, **kwargs): - r"""Ends a do-loop and starts the looping action. - - Mechanical APDL Command: `\*ENDDO `_ - - Notes - ----- - One :ref:`enddo` is required for each nested do-loop. The :ref:`enddo` command must appear on the same file as the :ref:`do` command, and all six characters must be input. - - This command is valid in any processor. - """ - command = f"*ENDDO" - return self.run(command, **kwargs) - - def endif(self, **kwargs): - r"""Ends an if-then-else. - - Mechanical APDL Command: `\*ENDIF `_ - - Notes - ----- - Required terminator for the if-then-else construct. See :ref:`if` for details. - - If a batch input stream hits an end-of-file during a false :ref:`if` condition, the analysis will not terminate normally. You will need to terminate it externally (use either the Linux "kill" function or the Windows task manager). The :ref:`endif` command must appear on the same file as the :ref:`if` command, and all six characters must be input. - - This command is valid in any processor. - """ - command = f"*ENDIF" - return self.run(command, **kwargs) - def starexit(self, **kwargs): r"""Exits a do-loop. @@ -187,57 +174,41 @@ def starexit(self, **kwargs): Notes ----- - The command following the :ref:`enddo` is executed next. The exit option may also be conditional [Use the :ref:`if` ]. The :ref:`starexit` command must appear on the same file as the :ref:`do` command. - - This command is valid in any processor. + The command following the :ref:`enddo` is executed next. The exit option may also be conditional + [Use the :ref:`if` ]. The :ref:`starexit` command must appear on the same file as the :ref:`do` + command. This command is valid in any processor. """ command = f"*EXIT" return self.run(command, **kwargs) - def stargo(self, base="", **kwargs): - r"""Causes a specified line on the input file to be read next. - - Mechanical APDL Command: `\*GO `_ - - Parameters - ---------- - base : str - "Go to" action: - - * ``:, label`` - A user-defined label (beginning with a colon (:), 8 characters maximum). - The - command reader will skip (and wrap to the beginning of the file, if necessary) to the first - line - that begins with the matching : ``label`` . - - .. warning:: - This label option may not be mixed with do-loop or if-then-else constructs. + def enddo(self, **kwargs): + r"""Ends a do-loop and starts the looping action. - * ``STOP`` - This action will cause an exit from the Mechanical APDL program at this line. + Mechanical APDL Command: `\*ENDDO `_ Notes ----- - Causes the next read to be from a specified line on the input file. Lines may be skipped or reread. The :ref:`stargo` command will `not` be executed unless it is part of a macro, user file (processed by :ref:`use` ), an alternate input file (processed by :ref:`input` ), or unless it is used in a batch-mode input stream. Jumping into, out of, or within a do-loop or an if-then-else construct to a : ``label`` line is not allowed. - - This command is valid in any processor. + One :ref:`enddo` is required for each nested do-loop. The :ref:`enddo` command must appear on the + same file as the :ref:`do` command, and all six characters must be input. This command is valid in + any processor. """ - command = f"*GO,{base}" + command = f"*ENDDO" return self.run(command, **kwargs) def repeat( self, - ntot="", - vinc1="", - vinc2="", - vinc3="", - vinc4="", - vinc5="", - vinc6="", - vinc7="", - vinc8="", - vinc9="", - vinc10="", - vinc11="", + ntot: str = "", + vinc1: str = "", + vinc2: str = "", + vinc3: str = "", + vinc4: str = "", + vinc5: str = "", + vinc6: str = "", + vinc7: str = "", + vinc8: str = "", + vinc9: str = "", + vinc10: str = "", + vinc11: str = "", **kwargs, ): r"""Repeats the previous command. @@ -250,35 +221,125 @@ def repeat( Number of times the preceding command is executed (including the initial execution). Must be 2 or greater. ``NTOT`` of 2 causes one repeat (for a total of 2 executions). - vinc1, vinc2, vinc3, . . ., vinc11 : str + vinc1 : str Value increments applied to first through eleventh data fields of the preceding command. - Notes - ----- - :ref:`repeat` must immediately follow the command that is to be repeated. The numeric arguments of the initial command may be incremented in the generated commands. The numeric increment values may be integer or real, positive or negative, zero or blank. Alphanumeric arguments cannot be incremented. For large values of ``NTOT``, consider printout suppression ( :ref:`nopr` command) first. + vinc2 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc3 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc4 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc5 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc6 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc7 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc8 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc9 : str + Value increments applied to first through eleventh data fields of the preceding command. + + vinc10 : str + Value increments applied to first through eleventh data fields of the preceding command. - Most commands beginning with slash (/), star (\*), as well as "unknown command" macros, cannot be repeated. For these commands, or if more than one command is to be repeated, include them within a do-loop. File switching commands (those reading additional commands) cannot be repeated. If a :ref:`repeat` command immediately follows another :ref:`repeat` command, the repeat action only applies to the last non- :ref:`repeat` command. Also, :ref:`repeat` should not be used in interactive mode immediately after a) a command (or its log file equivalent) that uses picking, or b) a command that requires a response from the user. + vinc11 : str + Value increments applied to first through eleventh data fields of the preceding command. - This command is valid in any processor. + Notes + ----- + :ref:`repeat` must immediately follow the command that is to be repeated. The numeric arguments of + the initial command may be incremented in the generated commands. The numeric increment values may + be integer or real, positive or negative, zero or blank. Alphanumeric arguments cannot be + incremented. For large values of ``NTOT``, consider printout suppression ( :ref:`nopr` command) + first. Most commands beginning with slash (/), star (\*), as well as "unknown command" macros, + cannot be repeated. For these commands, or if more than one command is to be repeated, include them + within a do-loop. File switching commands (those reading additional commands) cannot be repeated. If + a :ref:`repeat` command immediately follows another :ref:`repeat` command, the repeat action only + applies to the last non- :ref:`repeat` command. Also, :ref:`repeat` should not be used in + interactive mode immediately after a) a command (or its log file equivalent) that uses picking, or + b) a command that requires a response from the user. This command is valid in any processor. """ command = f"*REPEAT,{ntot},{vinc1},{vinc2},{vinc3},{vinc4},{vinc5},{vinc6},{vinc7},{vinc8},{vinc9},{vinc10},{vinc11}" return self.run(command, **kwargs) - def wait(self, dtime="", **kwargs): - r"""Causes a delay before the reading of the next command. + def dowhile(self, par: str = "", **kwargs): + r"""Loops repeatedly through the next :ref:`enddo` command. - Mechanical APDL Command: `/WAIT `_ + Mechanical APDL Command: `\*DOWHILE `_ Parameters ---------- - dtime : str - Time delay (in seconds). Maximum time delay is 59 seconds. + par : str + The name of the scalar parameter to be used as the loop index. There is no character parameter + substitution for the ``Par`` field. Notes ----- - The command following the :ref:`wait` will not be processed until the specified wait time increment has elapsed. Useful when reading from a prepared input file to cause a pause, for example, after a display command so that the display can be reviewed for a period of time. Another "wait" feature is available via the :ref:`ask` command. + :ref:`dowhile` loops repeatedly through the next :ref:`enddo` command as long as ``Par`` is greater + than zero. The block of commands following the :ref:`dowhile` command (up to the :ref:`enddo` + command) is executed repeatedly until some loop control is satisfied. Printout is automatically + suppressed on all loops after the first (include a :ref:`gopr` command to restore the printout). The + command line loop control ( ``Par`` ) must be input; however, :ref:`if` within the block can also be + used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level of internal file switching is + used for each nested :ref:`dowhile`. Twenty levels of nested do-loops are allowed. This command is + valid in any processor. + """ + command = f"*DOWHILE,{par}" + return self.run(command, **kwargs) - This command is valid in any processor. + def do( + self, par: str = "", ival: str = "", fval: str = "", inc: str = "", **kwargs + ): + r"""Defines the beginning of a do-loop. + + Mechanical APDL Command: `\*DO `_ + + Parameters + ---------- + par : str + The name of the scalar parameter to be used as the loop index. See :ref:`starset` for name + restrictions. Any existing parameter of the same name will be redefined. There is no character + parameter substitution for the ``Par`` field. + + ival : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + fval : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + inc : str + Initially assign ``IVAL`` to ``Par``. Increment ``IVAL`` by ``INC`` for each successive loop. If + ``IVAL`` exceeds ``FVAL`` and ``INC`` is positive, the loop is not executed. ``INC`` defaults to + 1. Negative increments and non-integer numbers are allowed. + + Notes + ----- + The block of commands following the :ref:`do` command (up to the :ref:`enddo` command) is executed + repeatedly until some loop control is satisfied. Printout is automatically suppressed on all loops + after the first (include a :ref:`gopr` command to restore the printout). The command line loop + control ( ``Par``, ``IVAL``, ``FVAL``, ``INC`` ) must be input; however, a Use the :ref:`if` + within the block can also be used to control looping ( :ref:`starexit`, :ref:`cycle` ). One level + of internal file switching is used for each nested :ref:`do`. Twenty levels of nested do-loops are + allowed. Do-loops that include :ref:`input`, :ref:`use`, or an "Unknown Command" macro, have less + nesting available because each of these operations also uses a level of file switching. The + :ref:`do`, :ref:`enddo`, and any :ref:`cycle` and :ref:`starexit` commands for a do-loop must all + be read from the same file (or keyboard). You cannot use the `MULTIPRO + `_ + or :ref:`create` commands within a :ref:`do` -loop. Picking operations should also not be used + within a :ref:`do` -loop. This command is valid in any processor. """ - command = f"/WAIT,{dtime}" + command = f"*DO,{par},{ival},{fval},{inc}" return self.run(command, **kwargs)