diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 337b190332..53da909290 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -57,8 +57,6 @@ jobs: doc-style: name: "Documentation style check" runs-on: ubuntu-latest - #Skipping until 2394 is fixed - if: github.ref == 'Skip for now' steps: - name: "Ansys documentation style checks" uses: ansys/actions/doc-style@v4 @@ -101,7 +99,7 @@ jobs: docs-build: name: "Build documentation" runs-on: ubuntu-latest - # needs: doc-style - Skip for now + needs: doc-style timeout-minutes: 60 outputs: PYMAPDL_VERSION: ${{ steps.version.outputs.PYMAPDL_VERSION }} diff --git a/doc/.vale.ini b/doc/.vale.ini index df6f7c71cc..7d2d583897 100644 --- a/doc/.vale.ini +++ b/doc/.vale.ini @@ -27,5 +27,7 @@ Vocab = ANSYS # Apply the following styles BasedOnStyles = Vale, Google +TokenIgnores = (:(func|class|meth|attr|py):`(?:.|\n)*?`)|(<.*>)|(.. code::.*\n| .*) + # Removing Google-specific rule - Not applicable under some circumstances Google.Colons = NO diff --git a/doc/source/api/unit_testing.rst b/doc/source/api/unit_testing.rst index aaef4a6815..a8a2bb33d5 100644 --- a/doc/source/api/unit_testing.rst +++ b/doc/source/api/unit_testing.rst @@ -1,6 +1,6 @@ .. _ref_unit_testing_contributing: -Unit Testing +Unit testing ============ Unit tests validate the software by testing that the logic @@ -8,7 +8,7 @@ implemented inside a certain method, class, or module is working as expected. They should be as atomic and independent as possible. -Unit testing is highly important. The tests check that code +Unit testing is highly important. The tests verify that code changes are consistent with other parts of the code and verify that these changes are implemented properly. @@ -34,7 +34,7 @@ Coverage example To show how the coverage works, assume that you have this library: -**My awesome library** +**Awesome library** .. code:: python @@ -87,8 +87,8 @@ Continuous Integration and Continuous Deployment (CI/CD) approach Unit tests and integration tests are part of Continuous Integration (CI). The automation of testing, monitoring, and deployment of newly added -code allows Continuous Deployment (CD) throughout the application -lifecycle, providing a comprehensive CI/CD approach. +code allows Continuous Deployment (CD) throughout the app lifecycle, +providing a comprehensive CI/CD approach. .. figure:: ../images/cicd.jpg :width: 300pt diff --git a/doc/source/examples/extended_examples/ex_01-gmsh_example/ex_01-gmsh_example.rst b/doc/source/examples/extended_examples/ex_01-gmsh_example/ex_01-gmsh_example.rst index 3cfcda7432..9515cda0ec 100644 --- a/doc/source/examples/extended_examples/ex_01-gmsh_example/ex_01-gmsh_example.rst +++ b/doc/source/examples/extended_examples/ex_01-gmsh_example/ex_01-gmsh_example.rst @@ -11,8 +11,8 @@ open source Python meshing library. For more information, visit the Gmsh website Description ----------- -Gmsh is used to import an external geometry file in STL format. The `pymapdl-reader `_ library -is then used to import the geometry into PyMAPDL. +Gmsh is used to import an external geometry file in STL format. The `PyMAPDL Reader `_ +library is then used to import the geometry into PyMAPDL. This example makes use of these files: diff --git a/doc/source/examples/extended_examples/gui/executable.rst b/doc/source/examples/extended_examples/gui/executable.rst index 042c405ea4..a80eeff5b1 100644 --- a/doc/source/examples/extended_examples/gui/executable.rst +++ b/doc/source/examples/extended_examples/gui/executable.rst @@ -160,7 +160,9 @@ The **Preprocessing** tab contains input fields for Poisson's ratio, Young modul Add a PyVista plotting frame in the window ========================================== -Start by importing the `QtInteractor `_ class from the ``pyvistaqt`` package and the :class:`MapdlTheme ` class from the ``ansys-mapdl-core`` package: +Start by importing the `QtInteractor `_ +class from the ``pyvistaqt`` package and the :class:`MapdlTheme ` +class from the ``ansys-mapdl-core`` package: .. code:: python diff --git a/doc/source/examples/extended_examples/index.rst b/doc/source/examples/extended_examples/index.rst index cf211167a5..b11463c440 100644 --- a/doc/source/examples/extended_examples/index.rst +++ b/doc/source/examples/extended_examples/index.rst @@ -11,7 +11,7 @@ with other programs, libraries, and features in development. +----------------------------+--------------------------------------------------------------------------------------------+ | `Cart-Pole Simulation`_ | Demonstrates a reinforcement machine learning example using MAPDL through PyMAPDL. | +----------------------------+--------------------------------------------------------------------------------------------+ -| :ref:`extended_example01` | Demonstrates the interoperability between PyMAPDL and the `gmsh `_ meshing library. | +| :ref:`extended_example01` | Demonstrates the interoperability between PyMAPDL and the `Gmsh `_ meshing library. | +----------------------------+--------------------------------------------------------------------------------------------+ | :ref:`python_upf_examples` | Demonstrates the interoperability between user-programmable functions in MAPDL and Python. | +----------------------------+--------------------------------------------------------------------------------------------+ diff --git a/doc/source/getting_started/running_mapdl.rst b/doc/source/getting_started/running_mapdl.rst index 70103bcf36..2603c73f2d 100644 --- a/doc/source/getting_started/running_mapdl.rst +++ b/doc/source/getting_started/running_mapdl.rst @@ -138,7 +138,7 @@ the mentioned IP address/hostname for this to work. If you have MAPDL installed on your local host, you can use the :func:`launch_mapdl() ` method to both start and connect to MAPDL. -If you have any problem launching PyMAPDL, see :ref:`debugging_launch_mapdl`. +If you have any problem launching PyMAPDL, see :ref:`Launching issues `. If you are connecting to an MAPDL Docker image, the procedure is the same. Just make sure that you specify the mapped port instead of the internal Docker image port. diff --git a/doc/source/user_guide/convert.rst b/doc/source/user_guide/convert.rst index f63fb52523..d7d34a050e 100644 --- a/doc/source/user_guide/convert.rst +++ b/doc/source/user_guide/convert.rst @@ -1,5 +1,6 @@ Translate scripts =================== + The `ansys-mapdl-core `_ library contains a few basic functions to translate existing MAPDL scripts into PyMAPDL scripts. Ideally, all math and variable setting @@ -8,7 +9,7 @@ are less transparent and more difficult to debug. Command-line interface -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- In PyMAPDL v0.64.0 and later, you use the converter from the command line. After you have activated and installed the package as described @@ -40,7 +41,7 @@ The ``pymapdl_convert_script`` command uses the Hence, this command accepts most of this function's arguments. Usage ------ +~~~~~ You can call this command from the terminal with different arguments. Here is an example that converts the ``mapdl.dat`` @@ -90,12 +91,13 @@ function documentation. Caveats ~~~~~~~ + These examples only show an automatic translation of a verification: file and not optimized code. Should it be necessary to pull -parameters or arrays from ansys, use the :func:`Mapdl.get_value() -` function, which is quite similar to the -MAPDL :func:`Mapdl.get() ` -command shown here: +parameters or arrays from ansys, use the +:func:`Mapdl.get_value() ` function, +which is quite similar to the MAPDL +:func:`Mapdl.get() ` command shown here: .. code:: pycon @@ -122,6 +124,7 @@ with: Script translation ~~~~~~~~~~~~~~~~~~ + Existing Ansys scripts can be translated using the :func:`convert_script() ` function: @@ -151,15 +154,14 @@ Or, you can convert code in form of strings for later processing using the The script conversion functions allow some interesting arguments, which you can see in the respective :func:`convert_script() ` and :func:`convert_apdl_block() ` -function documentation. Especially interesting are the ``add_imports``, ``comment_solve``, and -``print_com`` keyword arguments. - -Of particular note in the following examples is how most of the -commands can be called as a method to the Ansys object rather than -sending a string as a command. Additionally, take note that some -commands require the :attr:`Mapdl.non_interactive -` context manager since some -commands require and may break the server connection for some +function documentation. Especially interesting are the ``add_imports``, ``comment_solve``, +and ``print_com`` keyword arguments. + +Of particular note in the following examples is how most of the commands can be called +as a method to the Ansys object rather than sending a string as a command. Additionally, +take note that some commands require the +:attr:`Mapdl.non_interactive ` +context manager since some commands require and may break the server connection for some interfaces (such as CORBA) or are invalid (as in gRPC). Also note that APDL macros that use ``*CREATE`` have been replaced @@ -169,6 +171,7 @@ should it be necessary to insert a ``breakpoint()`` in the script. Example: VM1 - statically indeterminate reaction force analysis --------------------------------------------------------------- + Ansys MAPDL contains over 200 verification files used for Ansys validation and demonstration. These validation files are used here to demo the use of the PyMAPDL file translator :func:`convert_script() diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 2cd64af508..330af6785b 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -222,4 +222,4 @@ with it. For example: recommended. -For stability considerations, see :ref:`ref_pymapdl_stability`. +For stability considerations, see :ref:`PyMAPDL stability `. diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index 34c1b839a4..bfaa5dc813 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -17,8 +17,9 @@ Additionally, MAPDL commands containing a ``/`` or ``*`` have had those characters removed, unless this causes a conflict with an existing name. Most notable is ``/SOLU``, which would conflict with ``SOLU``. Therefore, -``/SOLU`` is renamed to the :func:`Mapdl.slashsolu() -` method to differentiate it from ``solu``. +``/SOLU`` is renamed to the +:func:`Mapdl.slashsolu() ` +method to differentiate it from ``solu``. Out of the 1500 MAPDL commands, about 15 start with ``slash (/)`` and 8 start with ``star (*)``. @@ -341,9 +342,9 @@ example: Prompts ~~~~~~~ Prompts from MAPDL automatically continued as if MAPDL is in batch -mode. Commands requiring user input, such as the :func:`Mapdl.vwrite() -` method fail and must be entered in -non-interactively. +mode. Commands requiring user input, such as the +:func:`Mapdl.vwrite() ` method fail +and must be entered in non-interactively. APDL command logging @@ -618,8 +619,8 @@ using the :attr:`Mapdl.chain_commands ` a The execution time using this approach is generally 4 to 10 times faster than running each command individually. You can then view the final response of -the chained commands with the :attr:`Mapdl.last_response -` attribute. +the chained commands with the +:attr:`Mapdl.last_response ` attribute. .. note:: Command chaining is not supported in distributed MAPDL. To improve diff --git a/doc/source/user_guide/parameters.rst b/doc/source/user_guide/parameters.rst index 09ebfc4aa9..f8cf0a8739 100644 --- a/doc/source/user_guide/parameters.rst +++ b/doc/source/user_guide/parameters.rst @@ -4,10 +4,11 @@ ********************************* Setting and retrieving parameters ********************************* -APDL parameters can be retrieved from and instance of :class:`Mapdl -` using the :attr:`Mapdl.parameters -`. For example, if you want to use -MAPDL's :func:`Mapdl.get() ` method to +APDL parameters can be retrieved from and instance of +:class:`Mapdl ` +using the :attr:`Mapdl.parameters `. +For example, if you want to use MAPDL's +:func:`Mapdl.get() ` method to populate a parameter, you can then access the parameter with code: .. code:: pycon @@ -46,7 +47,8 @@ ROUT``, you can access it with this code: For a full list of the methods and attributes available to the ``Parameters`` class, see :ref:`ref_parameters_api`. -For additional information on PyMAPDL array limitations, see :ref:`ref_numpy_arrays_in_mapdl`. +For additional information on PyMAPDL array limitations, see +:ref:`Issues when importing and exporting numpy arrays in MAPDL `. .. _ref_special_named_param: diff --git a/doc/source/user_guide/plotting.rst b/doc/source/user_guide/plotting.rst index 597118eaf8..f1f9df20dd 100644 --- a/doc/source/user_guide/plotting.rst +++ b/doc/source/user_guide/plotting.rst @@ -52,9 +52,9 @@ You plot lines within Python using the :func:`Mapdl.lplot() ` method. This example cuts the initial -area with the eight circles and then extrudes it. +visualize them using the :func:`Mapdl.vplot() ` +method. This example cuts the initial area with the eight circles and then +extrudes it. .. code:: pycon @@ -202,8 +202,8 @@ method: .. note:: Because boundary conditions can only target nodes, you can - only use ``plot_bc`` as an argument in the :func:`Mapdl.nplot() - ` method. + only use ``plot_bc`` as an argument in the + :func:`Mapdl.nplot() ` method. diff --git a/doc/source/user_guide/pool.rst b/doc/source/user_guide/pool.rst index 22af3fc372..efa975b1dc 100644 --- a/doc/source/user_guide/pool.rst +++ b/doc/source/user_guide/pool.rst @@ -2,12 +2,11 @@ Create a pool of MAPDL instances ================================ -PyMAPDL contains the :class:`LocalMapdlPool -` class to simplify creating multiple -local instances of the :class:`Mapdl ` -class for batch processing. This can be used for the batch processing of a -set of input files, convergence analysis, or other batch related -processes. +PyMAPDL contains the :class:`LocalMapdlPool ` +class to simplify creating multiple local instances of the +:class:`Mapdl ` class for batch processing. +This can be used for the batch processing of a set of input files, +convergence analysis, or other batch related processes. This code creates a pool: diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index a5337c7f7e..13610d5bad 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -1,10 +1,6 @@ - - - .. _ref_troubleshooting: -======================= Troubleshooting PyMAPDL ======================= @@ -13,9 +9,8 @@ To help you resolve any problems that you might have when using PyMAPDL, some of the most common problems and frequently asked questions are posted here. -***************** Debug in PyMAPDL -***************** +---------------- If you are having trouble with PyMAPDL, you can record some internal logs into a file using a logger. @@ -43,11 +38,10 @@ If you believe you have found a bug, open an issue on the `PyMAPDL Issues page `_. -.. _debugging_launch_mapdl: +.. _ref_launching_issue: -**************** Launching issues -**************** +---------------- There are several issues that can cause MAPDL not to launch, including: @@ -63,7 +57,7 @@ There are several issues that can cause MAPDL not to launch, including: Connection timeout -================== +~~~~~~~~~~~~~~~~~~ In some networks, MAPDL might take longer than expected to connect to the license server or to the remote instance. In those cases, you might see the following message: @@ -93,12 +87,11 @@ Or if you are connecting to a remote instance you can use: Testing MAPDL launching -======================= +~~~~~~~~~~~~~~~~~~~~~~~ In some cases, it may be necessary to run the launch command manually from the command line. -On Windows ----------- +**On Windows** Open up a command prompt and run the version-dependent command: @@ -109,8 +102,7 @@ Open up a command prompt and run the version-dependent command: .. note:: PowerShell users can run the preceding command without quotes. -On Linux --------- +**On Linux** Run the version-dependent command: @@ -153,7 +145,7 @@ If this command doesn't launch MAPDL, look at the command output: .. vale on Licensing issues -================ +~~~~~~~~~~~~~~~~ Incorrect license server configuration can prevent MAPDL from being able to get a valid license. In such cases, you might see output **similar** to: @@ -184,7 +176,7 @@ for maintaining Ansys licensing or have a personal install of Ansys, see the onl For more comprehensive information, download the :download:`ANSYS Licensing Guide `. Incorrect licensing environment variables ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The license server can be also specified using the environment variable :envvar:`ANSYSLMD_LICENSE_FILE`. The following code examples show how you can see the value of this environment variable on @@ -209,7 +201,7 @@ either Windows or Linux. .. _vpn_issues_troubleshooting: Virtual private network (VPN) issues -==================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From ANSYS 2022 R2 to ANSYS 2021 R1, MAPDL has issues launching when VPN software is running. One issue stems from MPI communication and can be solved by either passing @@ -248,18 +240,14 @@ On Windows, you can find the license configuration file that points to the licen .. _missing_dependencies_on_linux: Missing dependencies on Linux -============================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some Linux installations might be missing required dependencies. If you get errors like ``libXp.so.6: cannot open shared object file: No such file or directory``, you are likely missing some necessary dependencies. - -.. _installing_mapdl_on_centos7: - -CentOS 7 --------- +**CentOS 7** On CentOS 7, you can install missing dependencies with: @@ -268,10 +256,7 @@ On CentOS 7, you can install missing dependencies with: yum install openssl openssh-clients mesa-libGL mesa-libGLU motif libgfortran -.. _installing_mapdl_on_ubuntu: - -Ubuntu ------- +**Ubuntu** On Ubuntu 22.04, use this code to install the needed dependencies: @@ -300,8 +285,7 @@ using this code: apt-get install -y libxp6 -Ubuntu 20.04 and older ----------------------- +**Ubuntu 20.04 and older** If you are using Ubuntu 16.04, you can install ``libxp16`` with this code: @@ -333,7 +317,7 @@ then installs it via the ``dpkg`` package. .. _conflicts_student_version: Conflicts with student version -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Although you can install Ansys together with other Ansys products or versions, on Windows, you should not install a student version of an Ansys product together with its non-student version. @@ -353,7 +337,8 @@ to the correct location. ``SMP`` mode, unless another MPI option is specified. Incorrect environment variables -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you are using a non-standard install, you might need to manually set the environment variables ``ANSYSXXX_DIR``, ``AWP_ROOTXXX``, and ``CADOE_LIBDIRXXX`` to the correct location. @@ -387,7 +372,8 @@ shown. For Ansys MAPDL 2022 R2, ``222`` appears where ``XXX`` is shown. .. vale on Using a proxy server -==================== +~~~~~~~~~~~~~~~~~~~~ + In some rare cases, you might experience some problems to connect to the MAPDL instance if you are using a proxy. When `gRPC `_ is used in a proxy environment, if a local address is specified (that is ``127.0.0.1``) @@ -399,7 +385,8 @@ to connect to MAPDL instance. Firewall settings -================= +~~~~~~~~~~~~~~~~~ + MAPDL and Python should have the correct firewall settings to allow communication between the two. If you are using a firewall, you should allow MAPDL to receive inbound connections to the following ports: @@ -425,8 +412,12 @@ For more information on how to **configure your firewall on Ubuntu Linux**, plea link `Security-Firewall | Ubuntu `_. +Location of the executable file +------------------------------- + Manually set the location of the executable file -================================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you have a non-standard install, PyMAPDL might be unable find your MAPDL installation. If this is the case, provide the location of MAPDL as the first parameter to :func:`launch_mapdl() `. @@ -450,7 +441,7 @@ as the first parameter to :func:`launch_mapdl() ` Default location of the executable file ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The first time that you run PyMAPDL, it detects the available Ansys installations. @@ -520,20 +511,17 @@ method lists higher versions first and student versions last. information, see :ref:`conflicts_student_version`. -.. _ref_pymapdl_limitations: - -********************* PyMAPDL usage issues -********************* +-------------------- -.. _ref_numpy_arrays_in_mapdl: +.. _ref_issues_np_mapdl: -Issues when importing and exporting numpy arrays in MAPDL -========================================================= +Issues when importing and exporting NumPy arrays in MAPDL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Because of the way MAPDL is designed, there is no way to store an array where one or more dimensions are zero. -This can happens in numpy arrays, where its first dimension can be +This can happens in NumPy arrays, where its first dimension can be set to zero. For example: .. code:: pycon @@ -583,41 +571,40 @@ to one, have the same shape if later retrieved. True - .. _ref_pymapdl_stability: -***************** PyMAPDL stability -***************** +----------------- Recommendations -=============== +~~~~~~~~~~~~~~~ When connecting to an instance of MAPDL using gRPC (default), there are some cases where the MAPDL server might exit unexpectedly. There are several ways to improve MADPL performance and stability: Use ``mute`` to improve stability ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When possible, pass ``mute=True`` to individual MAPDL commands or -set it globally with the :func:`Mapdl.mute -` method. This disables streaming -back the response from MAPDL for each command and marginally -improves performance and stability. Consider having a debug flag in +set it globally with the :func:`Mapdl.mute ` +method. This disables streaming back the response from MAPDL for each command +and marginally improves performance and stability. Consider having a debug flag in your program or script so that you can turn on and off logging and verbosity as needed. Issues -====== +~~~~~~ .. note:: - MAPDL 2021 R1 has a stability issue with the :func:`Mapdl.input() - ` method. Avoid using input files if - possible. Attempt to use the :func:`Mapdl.upload() - ` method to upload nodes and elements and read them - in via the :func:`Mapdl.nread() ` and + + MAPDL 2021 R1 has a stability issue with the : + :func:`Mapdl.input() ` + method. Avoid using input files if possible. Attempt to use the + :func:`Mapdl.upload() ` method to upload + nodes and elements and read them in via the + :func:`Mapdl.nread() ` and :func:`Mapdl.eread() ` methods. diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt index f6c734f578..5c3da5e154 100644 --- a/doc/styles/Vocab/ANSYS/accept.txt +++ b/doc/styles/Vocab/ANSYS/accept.txt @@ -146,6 +146,7 @@ UPF UPFs viscoplastic vise +von VTK wan WAN