diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cf01f42ebb..faa1b2eae2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,10 +21,10 @@ env: # You should go up in number, if you go down (or repeat a previous value) # you might end up reusing a previous cache if it haven't been deleted already. # It applies 7 days retention policy by default. - RESET_PIP_CACHE: 4 - RESET_EXAMPLES_CACHE: 4 - RESET_DOC_BUILD_CACHE: 4 - RESET_AUTOSUMMARY_CACHE: 4 + RESET_PIP_CACHE: 5 + RESET_EXAMPLES_CACHE: 5 + RESET_DOC_BUILD_CACHE: 5 + RESET_AUTOSUMMARY_CACHE: 5 PACKAGE_NAME: PyMAPDL concurrency: diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 5bcf264475..0000000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _ref_index_api: - -============= -API Reference -============= -This section gives an overview of the API of several public PyMAPDL -classes, functions, and attributes. - -These methods may include some MAPDL commands but are generally -specific to pymapdl specific methods and classes (i.e. methods that -extend existing MAPDL methods in a pythonic manner). For classic -MAPDL commands mapped to PyMAPDL, see :ref:`ref_mapdl_commands`. - - -.. toctree:: - :maxdepth: 2 - :hidden: - - commands - database - geometry - helper - inline - logging - mapdl - math - mesh - parameters - plotting - pool - post - solution - xpl - diff --git a/doc/source/api/commands.rst b/doc/source/contribution_and_api/commands.rst similarity index 100% rename from doc/source/api/commands.rst rename to doc/source/contribution_and_api/commands.rst diff --git a/doc/source/api/database.rst b/doc/source/contribution_and_api/database.rst similarity index 100% rename from doc/source/api/database.rst rename to doc/source/contribution_and_api/database.rst diff --git a/doc/source/api/geometry.rst b/doc/source/contribution_and_api/geometry.rst similarity index 100% rename from doc/source/api/geometry.rst rename to doc/source/contribution_and_api/geometry.rst diff --git a/doc/source/api/helper.rst b/doc/source/contribution_and_api/helper.rst similarity index 100% rename from doc/source/api/helper.rst rename to doc/source/contribution_and_api/helper.rst diff --git a/doc/source/contributing.rst b/doc/source/contribution_and_api/index.rst similarity index 79% rename from doc/source/contributing.rst rename to doc/source/contribution_and_api/index.rst index 774fc031ee..a1f35a79b3 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contribution_and_api/index.rst @@ -1,8 +1,9 @@ .. _ref_contributing: -============ -Contributing -============ +==================== +Contributing and API +==================== + Overall guidance on contributing to a PyAnsys library appears in the `Contributing `_ topic in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar @@ -12,8 +13,10 @@ contribute to PyMAPDL. The following contribution information is specific to PyMAPDL. + Cloning the PyMAPDL Repository ------------------------------- +============================== + Run this code to clone and install the latest version of PyMAPDL in development mode: .. code:: @@ -25,7 +28,8 @@ Run this code to clone and install the latest version of PyMAPDL in development Posting Issues --------------- +============== + Use the `PyMAPDL Issues `_ page to submit questions, report bugs, and request new features. When possible, we recommend that you use these issue templates: @@ -38,7 +42,8 @@ If your issue does not fit into one of these categories, create your own issue. To reach the project support team, email `pyansys.support@ansys.com `_. Viewing PyMAPDL Documentation ------------------------------ +============================= + Documentation for the latest stable release of PyMAPDL is hosted at `PyMAPDL Documentation `_. @@ -47,7 +52,8 @@ Documentation for the latest development version, which tracks the This version is automatically kept up to date via GitHub actions. Testing MAPDL -------------- +============= + If you do not have MAPDL installed locally but still want to run the unit testing, you must set up the following environment variables. @@ -72,7 +78,8 @@ MAPDL service by default when the ``launch_mapdl`` function is used. Code Style ----------- +========== + PyMAPDL follows PEP8 standard as outlined in the `PyAnsys Development Guide `_ and implements style checking using `pre-commit `_. @@ -94,3 +101,38 @@ This way, it's not possible for you to push code that fails the style checks. Fo isort....................................................................Passed flake8...................................................................Passed codespell................................................................Passed + + +.. _ref_index_api: + +API Reference +============= +This section gives an overview of the API of several public PyMAPDL +classes, functions, and attributes. + +These methods may include some MAPDL commands but are generally +specific to pymapdl specific methods and classes (i.e. methods that +extend existing MAPDL methods in a pythonic manner). For classic +MAPDL commands mapped to PyMAPDL, see :ref:`ref_mapdl_commands`. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + commands + database + geometry + helper + inline + logging + mapdl + math + mesh + parameters + plotting + pool + post + solution + xpl + \ No newline at end of file diff --git a/doc/source/api/inline.rst b/doc/source/contribution_and_api/inline.rst similarity index 100% rename from doc/source/api/inline.rst rename to doc/source/contribution_and_api/inline.rst diff --git a/doc/source/api/logging.rst b/doc/source/contribution_and_api/logging.rst similarity index 100% rename from doc/source/api/logging.rst rename to doc/source/contribution_and_api/logging.rst diff --git a/doc/source/api/mapdl.rst b/doc/source/contribution_and_api/mapdl.rst similarity index 100% rename from doc/source/api/mapdl.rst rename to doc/source/contribution_and_api/mapdl.rst diff --git a/doc/source/api/math.rst b/doc/source/contribution_and_api/math.rst similarity index 100% rename from doc/source/api/math.rst rename to doc/source/contribution_and_api/math.rst diff --git a/doc/source/api/mesh.rst b/doc/source/contribution_and_api/mesh.rst similarity index 100% rename from doc/source/api/mesh.rst rename to doc/source/contribution_and_api/mesh.rst diff --git a/doc/source/api/parameters.rst b/doc/source/contribution_and_api/parameters.rst similarity index 100% rename from doc/source/api/parameters.rst rename to doc/source/contribution_and_api/parameters.rst diff --git a/doc/source/api/plotting.rst b/doc/source/contribution_and_api/plotting.rst similarity index 100% rename from doc/source/api/plotting.rst rename to doc/source/contribution_and_api/plotting.rst diff --git a/doc/source/api/pool.rst b/doc/source/contribution_and_api/pool.rst similarity index 100% rename from doc/source/api/pool.rst rename to doc/source/contribution_and_api/pool.rst diff --git a/doc/source/api/post.rst b/doc/source/contribution_and_api/post.rst similarity index 100% rename from doc/source/api/post.rst rename to doc/source/contribution_and_api/post.rst diff --git a/doc/source/api/solution.rst b/doc/source/contribution_and_api/solution.rst similarity index 100% rename from doc/source/api/solution.rst rename to doc/source/contribution_and_api/solution.rst diff --git a/doc/source/api/xpl.rst b/doc/source/contribution_and_api/xpl.rst similarity index 100% rename from doc/source/api/xpl.rst rename to doc/source/contribution_and_api/xpl.rst diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 9f75fd98ad..3568e7393c 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -17,7 +17,6 @@ getting a licensed copy of Ansys. versioning docker using_julia - faq wsl ************ diff --git a/doc/source/getting_started/running_mapdl.rst b/doc/source/getting_started/running_mapdl.rst index 041f1d48bb..df00b8a53b 100644 --- a/doc/source/getting_started/running_mapdl.rst +++ b/doc/source/getting_started/running_mapdl.rst @@ -139,315 +139,4 @@ the mentioned IP/hostname for this to work. If you have MAPDL installed on your local host, you can use ``launch_mapdl`` to both start and connect to MAPDL. - -Debugging Launching MAPDL -------------------------- -For any number of reasons, Python may fail to launch MAPDL. Here's -some approaches to debug the start: - - -Manually Set the Executable Location -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you have a non-standard install, ``pymapdl`` may be unable find -your installation. If that's the case, provide the location of MAPDL -as the first parameter to ``launch_mapdl``. For example, on Windows, -this will be: - -.. code:: python - - >>> from ansys.mapdl.core import launch_mapdl - >>> exec_loc = 'C:/Program Files/ANSYS Inc/v211/ansys/bin/winx64/ANSYS211.exe' - >>> mapdl = launch_mapdl(exec_loc) - -For Linux: - -.. code:: python - - >>> from ansys.mapdl.core import launch_mapdl - >>> exec_loc = '/usr/ansys_inc/v211/ansys/bin/ansys211' - >>> mapdl = launch_mapdl(exec_loc) - -Should this fail to launch or hang while launching, pass -``verbose_mapdl=True`` when using ``launch_mapdl``. This will print -the output of MAPDL within Python and can be used to debug why MAPDL -isn't launching. On Windows, output is limited due to the way -MAPDL launches. - -Default Executable Location -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The first time that you run PyMAPDL, it detects the -available ANSYS installations. - -On Windows, Ansys installations are normally under: - -.. code:: text - - C:/Program Files/ANSYS Inc/vXXX - -On Linux, Ansys installations are normally under: - -.. code:: text - - /usr/ansys_inc/vXXX - -If PyMAPDL finds a valid ANSYS installation, it caches its -path in the configuration file, ``config.txt``, whose path is shown in the -following code: - -.. code:: python - - >>> from ansys.mapdl.core.launcher import CONFIG_FILE - >>> print(CONFIG_FILE) - 'C:\\Users\\user\\AppData\\Local\\ansys_mapdl_core\\ansys_mapdl_core\\config.txt' - - -In certain cases, this configuration might become obsolete. For example, when a new -Ansys version is installed and an earlier installation is removed. -To update this configuration file with the latest path, use: - -.. code:: python - - >>> from ansys.mapdl.core import save_ansys_path - >>> save_ansys_path(r"C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ansys222.exe") - 'C:\\Program Files\\ANSYS Inc\\v222\\ansys\\bin\\winx64\\ansys222.exe' - -If you want to check which Ansys installations PyMAPDL has detected, use: - -.. code:: python - - >>> from ansys.mapdl.core.launcher import _get_available_base_ansys - >>> _get_available_base_ansys() - {222: 'C:\\Program Files\\ANSYS Inc\\v222', - 212: 'C:\\Program Files\\ANSYS Inc\\v212', - -222: 'C:\\Program Files\\ANSYS Inc\\ANSYS Student\\v222'} - -Student versions are provided as negative versions because the Python dictionary -does not accept two equal keys. The result of the ``_get_available_base_ansys()`` method -lists higher versions first and student versions last. - -.. warning:: - You should not have the same Ansys product version and student version installed. For more - information, see `Debug Launch Issues`_. - -Debug Launch Issues -~~~~~~~~~~~~~~~~~~~ -In some cases, it may be necessary to debug why MAPDL isn't launching -by running the launch command manually from the command line. In -Windows, open up a command prompt and run the following (version -dependent) command: - -.. code:: - - "C:\Program Files\ANSYS Inc\v211\ansys\bin\winx64\ANSYS211.exe" - -.. note:: - Powershell users can run the above without quotes. - - -For Linux: - -.. code:: - - /usr/ansys_inc/v211/ansys/bin/ansys211 - -You should start MAPDL in a temporary working directory because MAPDL creates -several temporary files. - -You can specify a directory by launching MAPDL from the temporary directory: - -.. code:: pwsh - - mkdir temporary_directory - cd temporary_directory - & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' - -Or, you can specify the directory using the ``-dir`` flag: - -.. code:: pwsh - - mkdir temporary_directory - & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' -dir "C:\ansys_job\mytest1" - - -If this command doesn't launch MAPDL, look at the command output: - -.. code:: pwsh - - (base) PS C:\Users\user\temp> & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' - *** ERROR *** - Another Ansys job with the same job name (file) is already running in this - directory or the file.lock file has not been deleted from an abnormally - terminated Ansys run. To disable this check, set the ANSYS_LOCK environment - variable to OFF. - - -There are many issues that can cause Ansys not to launch, including: - -- License server setup -- Running behind a VPN -- Missing dependencies -- Conflicts with a student version - - -Licensing Issues ----------------- - -Incorrect license server configuration can prevent Ansys from being able to get a valid license. -In those cases, you might see output **similar** to: - -.. code:: pwsh - - (base) PS C:\Users\user\temp> & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' - - ANSYS LICENSE MANAGER ERROR: - - Maximum licensed number of demo users already reached. - - - ANSYS LICENSE MANAGER ERROR: - - Request name mech_2 does not exist in the licensing pool. - No such feature exists. - Feature: mech_2 - License path: C:\Users\user\AppData\Local\Temp\\cb0400ba-6edb-4bb9-a333-41e7318c007d; - FlexNet Licensing error:-5,357 - - -PADT generally has a great blog regarding ANSYS issues, and licensing is always a common issue -(for example `Changes to Licensing at ANSYS 2020R1 `_). -Should you be responsible for maintaining Ansys licensing or have a personal install of Ansys, -please check the online Ansys licensing documentation at -`Installation and Licensing `_. - -For more comprehensive information, download the :download:`ANSYS Licensing Guide `. - - -VPN Issues ----------- -Sometimes, MAPDL has issues starting when VPN software is running. One -issue stems from MPI communication and can be solved by passing -the ``-smp`` option that sets the execution mode to "Shared Memory -Parallel", rather than the default "Distributed Memory Parallel" mode. - -.. code:: - - >>> from ansys.mapdl.core import launch_mapdl - >>> mapdl = launch_mapdl(additional_switches='-smp') - -While this approach has the disadvantage of using the potentially slower shared memory parallel mode, you'll at least be able to run MAPDL. For more details on shared vs distributed memory, see `High-Performance Computing for Mechanical Simulations using ANSYS `_. - - -In addition, if your device is inside a virtual private network (VPN), ANSYS might have some problems to correctly -resolve the IP of the license server. Please do check that the hostname or IP of the license server -is correct. -In Windows, you can find the license configuration file that points to the license server in: - -.. code:: text - - C:\Program Files\ANSYS Inc\Shared Files\Licensing\ansyslmd.ini - - -Incorrect environment variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The license server can be also specified using the environment variable ``ANSYSLMD_LICENSE_FILE``. -You can check the value of this environment variable by issuing on Windows: - - .. code:: pwsh - - $env:ANSYSLMD_LICENSE_FILE - 1055@1.1.1.1 - - And on linux: - - .. code:: bash - - printenv | grep ANSYSLMD_LICENSE_FILE - - -Missing Dependencies on Linux ------------------------------ -Some Linux installations may be missing required dependencies. Should -you get errors like ``libXp.so.6: cannot open shared object file: No -such file or directory``, you may be missing some necessary -dependencies. - -CentOS -~~~~~~ -On CentOS 7, you can install these with: - -.. code:: - - yum install openssl openssh-clients mesa-libGL mesa-libGLU motif libgfortran - - -Ubuntu -~~~~~~ -Since MAPDL isn't officially supported on Ubuntu, it's a bit more -difficult to setup, but it's still possible. On Ubuntu 20.04 with -Ansys 2021R1, install the following: - -.. code:: - - sudo apt-get install libx11-6 libgl1 libxm4 libxt6 libxext6 libxi6 libx11-6 libsm6 libice6 libxxf86vm1 libglu1 - -This takes care of everything except for ``libxp6``. Should you be -using Ubuntu 16.04, you can install that simply with ``sudo apt -install libxp6``. However, on Ubuntu 18.04+, you must manually -download and install the package. - -Since ``libxpl6`` also pre-depends on ``multiarch-support``, which is -also outdated, it must be removed, otherwise you'll have a broken -package configuration. The following step downloads and modifies the -``libxp6`` package to remove the ``multiarch-support`` dependency, and -then installs it via ``dpkg``. - -.. code:: - - cd /tmp - wget http://ftp.br.debian.org/debian/pool/main/libx/libxp/libxp6_1.0.2-2_amd64.deb - ar x libxp6_1.0.2-2_amd64.deb - sudo tar xzf control.tar.gz - sudo sed '/Pre-Depends/d' control -i - sudo bash -c "tar c postinst postrm md5sums control | gzip -c > control.tar.gz" - sudo ar rcs libxp6_1.0.2-2_amd64_mod.deb debian-binary control.tar.gz data.tar.xz - sudo dpkg -i ./libxp6_1.0.2-2_amd64_mod.deb - - - -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. -For example, installing both the Ansys MAPDL 202 2R2 Student Version and Ansys MAPDL 2022 -R2 might cause license conflicts due to overwriting of environment variables. Having different -versions, for example the Ansys MAPDL 2022 R2 Student Version and Ansys MAPDL 2021 R1, -is fine. - -If you experience issues, you should edit these environment variables to remove any -reference to the student version: ``ANSYSXXX_DIR``, ``AWP_ROOTXXX``, and -``CADOE_LIBDIRXXX``. The three-digit MAPDL version appears where ``XXX`` is -shown. For Ansys MAPDL 2022 R2, ``222`` appears where ``XXX`` is shown. - -.. code:: pwsh - - PS echo $env:AWP_ROOT222 - C:\Program Files\ANSYS Inc\ANSYS Student\v222 - PS $env:AWP_ROOT222 = "C:\Program Files\ANSYS Inc\v222" # This will overwrite the env var for the terminal session only. - PS [System.Environment]::SetEnvironmentVariable('AWP_ROOT222','C:\Program Files\ANSYS Inc\v222',[System.EnvironmentVariableTarget]::User) # This will change the env var permanently. - PS echo $env:AWP_ROOT222 - C:\Program Files\ANSYS Inc\v222 - - PS echo $env:ANSYS222_DIR - C:\Program Files\ANSYS Inc\ANSYS Student\v222\ANSYS - PS [System.Environment]::SetEnvironmentVariable('ANSYS222_DIR','C:\Program Files\ANSYS Inc\v222\ANSYS',[System.EnvironmentVariableTarget]::User) - PS echo $env:ANSYS222_DIR - C:\Program Files\ANSYS Inc\v222\ANSYS - - PS echo $env:CADOE_LIBDIR222 - C:\Program Files\ANSYS Inc\ANSYS Student\v222\CommonFiles\Language\en-us - PS [System.Environment]::SetEnvironmentVariable('CADOE_LIBDIR222','C:\Program Files\ANSYS Inc\v222\CommonFiles\Language\en-us',[System.EnvironmentVariableTarget]::User) - PS echo $env:CADOE_LIBDIR222 - C:\Program Files\ANSYS Inc\v222\CommonFiles\Language\en-us +If you find any problem launching PyMAPDL, please check :ref:`debugging_launch_mapdl` diff --git a/doc/source/index.rst b/doc/source/index.rst index 211c080ed7..7687e2c413 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -7,11 +7,11 @@ PyMAPDL Documentation |version| getting_started/index user_guide/index - api/index mapdl_commands/index examples/index learning/index - contributing + troubleshoot/index + contribution_and_api/index diff --git a/doc/source/getting_started/ANSYS_Inc._Licensing_Guide.pdf b/doc/source/troubleshoot/ANSYS_Inc._Licensing_Guide.pdf similarity index 100% rename from doc/source/getting_started/ANSYS_Inc._Licensing_Guide.pdf rename to doc/source/troubleshoot/ANSYS_Inc._Licensing_Guide.pdf diff --git a/doc/source/getting_started/faq.rst b/doc/source/troubleshoot/faq.rst similarity index 100% rename from doc/source/getting_started/faq.rst rename to doc/source/troubleshoot/faq.rst diff --git a/doc/source/troubleshoot/index.rst b/doc/source/troubleshoot/index.rst new file mode 100644 index 0000000000..5997347a9d --- /dev/null +++ b/doc/source/troubleshoot/index.rst @@ -0,0 +1,15 @@ +.. _ref_troubleshooting: + +=============== +Troubleshooting +=============== + +In order to help the users to overcome any problem they might have when using PyMAPDL, +some of the most common problems and frequently asked questions are posted here. + + +.. toctree:: + :maxdepth: 3 + + troubleshoot + faq diff --git a/doc/source/troubleshoot/troubleshoot.rst b/doc/source/troubleshoot/troubleshoot.rst new file mode 100644 index 0000000000..94dc11a95c --- /dev/null +++ b/doc/source/troubleshoot/troubleshoot.rst @@ -0,0 +1,441 @@ + + +.. _debugging_launch_mapdl: + +======================= +Troubleshooting PyMAPDL +======================= + + +***************** +Launching MAPDL +***************** + +For any number of reasons, Python may fail to launch MAPDL. Here's +some approaches to debug the start: + +In some cases, it may be necessary to debug why MAPDL isn't launching +by running the launch command manually from the command line. In +Windows, open up a command prompt and run the following (version +dependent) command: + +.. code:: + + "C:\Program Files\ANSYS Inc\v211\ansys\bin\winx64\ANSYS211.exe" + +.. note:: + Powershell users can run the above without quotes. + + +For Linux: + +.. code:: + + /usr/ansys_inc/v211/ansys/bin/ansys211 + +You should start MAPDL in a temporary working directory because MAPDL creates +several temporary files. + +You can specify a directory by launching MAPDL from the temporary directory: + +.. code:: pwsh + + mkdir temporary_directory + cd temporary_directory + & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' + +Or, you can specify the directory using the ``-dir`` flag: + +.. code:: pwsh + + mkdir temporary_directory + & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' -dir "C:\ansys_job\mytest1" + + +If this command doesn't launch MAPDL, look at the command output: + +.. code:: pwsh + + (base) PS C:\Users\user\temp> & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' + *** ERROR *** + Another Ansys job with the same job name (file) is already running in this + directory or the file.lock file has not been deleted from an abnormally + terminated Ansys run. To disable this check, set the ANSYS_LOCK environment + variable to OFF. + + +There are many issues that can cause Ansys not to launch, including: + +- License server setup +- Running behind a VPN +- Missing dependencies +- Conflicts with a student version + + +Licensing Issues +================ + +Incorrect license server configuration can prevent Ansys from being able to get a valid license. +In those cases, you might see output **similar** to: + +.. code:: pwsh + + (base) PS C:\Users\user\temp> & 'C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ANSYS222.exe' + + ANSYS LICENSE MANAGER ERROR: + + Maximum licensed number of demo users already reached. + + + ANSYS LICENSE MANAGER ERROR: + + Request name mech_2 does not exist in the licensing pool. + No such feature exists. + Feature: mech_2 + License path: C:\Users\user\AppData\Local\Temp\\cb0400ba-6edb-4bb9-a333-41e7318c007d; + FlexNet Licensing error:-5,357 + + +PADT has a great blog regarding ANSYS issues, and licensing is always a common issue +(for example `Changes to Licensing at ANSYS 2020R1 `_). +Should you be responsible for maintaining Ansys licensing or have a personal install of Ansys, +please check the online Ansys licensing documentation at +`Installation and Licensing `_. + +For more comprehensive information, download the :download:`ANSYS Licensing Guide `. + + +VPN Issues +========== + +Sometimes, MAPDL has issues starting when VPN software is running. One +issue stems from MPI communication and can be solved by passing +the ``-smp`` option that sets the execution mode to "Shared Memory +Parallel", rather than the default "Distributed Memory Parallel" mode. + +.. code:: + + >>> from ansys.mapdl.core import launch_mapdl + >>> mapdl = launch_mapdl(additional_switches='-smp') + +While this approach has the disadvantage of using the potentially slower shared +memory parallel mode, you'll at least be able to run MAPDL. +For more details on shared vs distributed memory, see +`High-Performance Computing for Mechanical Simulations using ANSYS `_. + + +In addition, if your device is inside a virtual private network (VPN), ANSYS might have some problems to correctly +resolve the IP of the license server. Please do check that the hostname or IP of the license server +is correct. +In Windows, you can find the license configuration file that points to the license server in: + +.. code:: text + + C:\Program Files\ANSYS Inc\Shared Files\Licensing\ansyslmd.ini + + +Incorrect environment variables +=============================== + +The license server can be also specified using the environment variable ``ANSYSLMD_LICENSE_FILE``. +You can check the value of this environment variable by issuing on Windows: + + .. code:: pwsh + + $env:ANSYSLMD_LICENSE_FILE + 1055@1.1.1.1 + + And on linux: + + .. code:: bash + + printenv | grep ANSYSLMD_LICENSE_FILE + + +Missing Dependencies on Linux +============================= + +Some Linux installations may be missing required dependencies. Should +you get errors like ``libXp.so.6: cannot open shared object file: No +such file or directory``, you may be missing some necessary +dependencies. + +CentOS +------ + +On CentOS 7, you can install these with: + +.. code:: + + yum install openssl openssh-clients mesa-libGL mesa-libGLU motif libgfortran + + +Ubuntu +------ + +Since MAPDL isn't officially supported on Ubuntu, it's a bit more +difficult to setup, but it's still possible. On Ubuntu 20.04 with +Ansys 2021R1, install the following: + +.. code:: + + sudo apt-get install libx11-6 libgl1 libxm4 libxt6 libxext6 libxi6 libx11-6 libsm6 libice6 libxxf86vm1 libglu1 + +This takes care of everything except for ``libxp6``. Should you be +using Ubuntu 16.04, you can install that simply with ``sudo apt +install libxp6``. However, on Ubuntu 18.04+, you must manually +download and install the package. + +Since ``libxpl6`` also pre-depends on ``multiarch-support``, which is +also outdated, it must be removed, otherwise you'll have a broken +package configuration. The following step downloads and modifies the +``libxp6`` package to remove the ``multiarch-support`` dependency, and +then installs it via ``dpkg``. + +.. code:: + + cd /tmp + wget http://ftp.br.debian.org/debian/pool/main/libx/libxp/libxp6_1.0.2-2_amd64.deb + ar x libxp6_1.0.2-2_amd64.deb + sudo tar xzf control.tar.gz + sudo sed '/Pre-Depends/d' control -i + sudo bash -c "tar c postinst postrm md5sums control | gzip -c > control.tar.gz" + sudo ar rcs libxp6_1.0.2-2_amd64_mod.deb debian-binary control.tar.gz data.tar.xz + sudo dpkg -i ./libxp6_1.0.2-2_amd64_mod.deb + + +.. _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. +For example, installing both the Ansys MAPDL2022 R2 Student Version and Ansys MAPDL 2022 +R2 might cause license conflicts due to overwriting of environment variables. Having different +versions, for example the Ansys MAPDL 2022 R2 Student Version and Ansys MAPDL 2021 R1, +is fine. + +If you experience issues, you should edit these environment variables to remove any +reference to the student version: ``ANSYSXXX_DIR``, ``AWP_ROOTXXX``, and +``CADOE_LIBDIRXXX``. The three-digit MAPDL version appears where ``XXX`` is +shown. For Ansys MAPDL 2022 R2, ``222`` appears where ``XXX`` is shown. + +.. code:: pwsh + + PS echo $env:AWP_ROOT222 + C:\Program Files\ANSYS Inc\ANSYS Student\v222 + PS $env:AWP_ROOT222 = "C:\Program Files\ANSYS Inc\v222" # This will overwrite the env var for the terminal session only. + PS [System.Environment]::SetEnvironmentVariable('AWP_ROOT222','C:\Program Files\ANSYS Inc\v222',[System.EnvironmentVariableTarget]::User) # This will change the env var permanently. + PS echo $env:AWP_ROOT222 + C:\Program Files\ANSYS Inc\v222 + + PS echo $env:ANSYS222_DIR + C:\Program Files\ANSYS Inc\ANSYS Student\v222\ANSYS + PS [System.Environment]::SetEnvironmentVariable('ANSYS222_DIR','C:\Program Files\ANSYS Inc\v222\ANSYS',[System.EnvironmentVariableTarget]::User) + PS echo $env:ANSYS222_DIR + C:\Program Files\ANSYS Inc\v222\ANSYS + + PS echo $env:CADOE_LIBDIR222 + C:\Program Files\ANSYS Inc\ANSYS Student\v222\CommonFiles\Language\en-us + PS [System.Environment]::SetEnvironmentVariable('CADOE_LIBDIR222','C:\Program Files\ANSYS Inc\v222\CommonFiles\Language\en-us',[System.EnvironmentVariableTarget]::User) + PS echo $env:CADOE_LIBDIR222 + C:\Program Files\ANSYS Inc\v222\CommonFiles\Language\en-us + + + +***************** +Launching PyMAPDL +***************** + +Even if you are able to correctly launch MAPDL, PyMAPDL might have some problems to launch +MAPDL. + + + +Manually Set the Executable Location +==================================== +If you have a non-standard install, ``pymapdl`` may be unable find +your installation. If that's the case, provide the location of MAPDL +as the first parameter to :func:`launch_mapdl() `. For example, on Windows, +this will be: + +.. code:: python + + >>> from ansys.mapdl.core import launch_mapdl + >>> exec_loc = 'C:/Program Files/ANSYS Inc/v211/ansys/bin/winx64/ANSYS211.exe' + >>> mapdl = launch_mapdl(exec_loc) + +For Linux: + +.. code:: python + + >>> from ansys.mapdl.core import launch_mapdl + >>> exec_loc = '/usr/ansys_inc/v211/ansys/bin/ansys211' + >>> mapdl = launch_mapdl(exec_loc) + +Should this fail to launch or hang while launching, pass +``verbose_mapdl=True`` when using :func:`launch_mapdl() `. This will print +the output of MAPDL within Python and can be used to debug why MAPDL +isn't launching. On Windows, output is limited due to the way +MAPDL launches. + + +Default Executable Location +=========================== + +The first time that you run PyMAPDL, it detects the +available Ansys installations. + +On Windows, Ansys installations are normally under: + +.. code:: text + + C:/Program Files/ANSYS Inc/vXXX + +On Linux, Ansys installations are normally under: + +.. code:: text + + /usr/ansys_inc/vXXX + +If PyMAPDL finds a valid Ansys installation, it caches its +path in the configuration file, ``config.txt``, whose path is shown in the +following code: + +.. code:: python + + >>> from ansys.mapdl.core.launcher import CONFIG_FILE + >>> print(CONFIG_FILE) + 'C:\\Users\\user\\AppData\\Local\\ansys_mapdl_core\\ansys_mapdl_core\\config.txt' + + +In certain cases, this configuration might become obsolete. For example, when a new +Ansys version is installed and an earlier installation is removed. +To update this configuration file with the latest path, use: + +.. code:: python + + >>> from ansys.mapdl.core import save_ansys_path + >>> save_ansys_path(r"C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ansys222.exe") + 'C:\\Program Files\\ANSYS Inc\\v222\\ansys\\bin\\winx64\\ansys222.exe' + +If you want to check which Ansys installations PyMAPDL has detected, use: + +.. code:: python + + >>> from ansys.mapdl.core.launcher import get_available_ansys_installations + >>> get_available_ansys_installations() + {222: 'C:\\Program Files\\ANSYS Inc\\v222', + 212: 'C:\\Program Files\\ANSYS Inc\\v212', + -222: 'C:\\Program Files\\ANSYS Inc\\ANSYS Student\\v222'} + +Student versions are provided as **negative** versions because the Python dictionary +does not accept two equal keys. The result of the +:func:`get_available_ansys_installations() ` +method lists higher versions first and student versions last. + +.. warning:: + You should not have the same Ansys product version and student version installed. For more + information, see :ref:`conflicts_student_version`. + + + +.. _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 performance and stability of MADPL: + +- When possible, pass ``mute=True`` to individual MAPDL commands or + set it globally with :func:`Mapdl.mute + `. This disables streaming + back the response from MAPDL for each command and will marginally + improve performance and stability. Consider having a debug flag in + your program or script so you can enable or disable logging and + verbosity when needed. + + +Issues +====== + +.. note:: + MAPDL 2021R1 has a stability issue with :func:`Mapdl.input() + `. Avoid using input files if + possible. Attempt to :func:`Mapdl.upload() + ` nodes and elements and read them + in via :func:`Mapdl.nread() ` and + :func:`Mapdl.eread() `. + + + + + +.. _ref_pymapdl_limitations: + +******************* +PyMAPDL Limitations +******************* + + +.. _ref_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 +set to zero. For example: + +.. code:: python + + >>> import numpy + >>> from ansys.mapdl.core import launch_mapdl + >>> mapdl = launch_mapdl() + >>> my_array = np.reshape([1, 2, 3, 4], (4,)) + >>> my_array + array([1, 2, 3, 4]) + + +These types of array dimensions will be always converted to ``1``. +For example: + +.. code:: python + + >>> mapdl.parameters['mapdlarray'] = my_array + >>> mapdl.parameters['mapdlarray'] + array([[1.], + [2.], + [3.], + [4.]]) + >>> mapdl.parameters['mapdlarray'].shape + (4, 1) + +This means that when you pass two arrays, one with the second axis equal +to zero (e.g. ``my_array``) and another one with the second axis equal +to one, if later retrieved, they will have the same shape. + +.. code:: python + + >>> my_other_array = np.reshape([1, 2, 3, 4], (4,1)) + >>> my_other_array + array([[1], + [2], + [3], + [4]]) + >>> mapdl.parameters['mapdlarray_b'] = my_other_array + >>> mapdl.parameters['mapdlarray_b'] + array([[1.], + [2.], + [3.], + [4.]]) + >>> np.allclose(mapdl.parameters['mapdlarray'], mapdl.parameters['mapdlarray_b']) + True \ No newline at end of file diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 49595b3345..0485e7f8ee 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -221,29 +221,4 @@ within it. For example: recommended. -Remote Stability Considerations -------------------------------- -.. note:: - This is only valid for instances of MAPDL launched in 2021R1 or - newer launching with ``mode=grpc`` (default). - -When connecting to a remote instance of MAPDL, there are some cases -where the MAPDL server will exit unexpectedly. These issues are being -corrected and will be solved in 2021R2, but for the time being, there -are several ways to improve performance and stability of MADPL: - -- When possible, pass ``mute=True`` to individual MAPDL commands or - set it globally with :func:`Mapdl.mute - `. This disables streaming - back the response from MAPDL for each command and will marginally - improve performance and stability. Consider having a debug flag in - your program or script so you can enable or disable logging and - verbosity when needed. - -.. note:: - MAPDL 2021R1 has a stability issue with :func:`Mapdl.input() - `. Avoid using input files if - possible. Attempt to :func:`Mapdl.upload() - ` nodes and elements and read them - in via :func:`Mapdl.nread() ` and - :func:`Mapdl.eread() `. +Visit :ref:`ref_pymapdl_stability` for stability considerations. diff --git a/doc/source/user_guide/parameters.rst b/doc/source/user_guide/parameters.rst index a3a9c78c93..2aece0ac7d 100644 --- a/doc/source/user_guide/parameters.rst +++ b/doc/source/user_guide/parameters.rst @@ -46,7 +46,8 @@ ROUT``, you can access it with: For a full listing of the methods and attributes available to the ``Parameters`` class, please reference the :ref:`ref_parameters_api`. - +Please visit :ref:`ref_numpy_arrays_in_mapdl` for further information about +PyMAPDL array limitations. .. _ref_special_named_param: @@ -136,60 +137,3 @@ For example: >>> print(mapdl.parameters['_param_']) 1.0 - -.. _ref_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 dimension is zero. -This can happens in Numpy arrays, where its first dimension can be -set to zero. - -.. code:: python - - >>> import numpy - >>> from ansys.mapdl.core import launch_mapdl - >>> mapdl = launch_mapdl() - >>> array40 = np.reshape([1, 2, 3, 4], (4,)) - >>> array40 - array([1, 2, 3, 4]) - - -These types of array dimensions will be always converted to ``1``. -For example: - -.. code:: python - - >>> mapdl.parameters['mapdlarray40'] = array40 - >>> mapdl.parameters['mapdlarray40'] - array([[1.], - [2.], - [3.], - [4.]]) - >>> mapdl.parameters['mapdlarray40'].shape - (4, 1) - -This means that when you pass two arrays, one with the second axis equal -to zero (e.g. ``array40``) and another one with the second axis equal -to one, if later retrieved, they will have the same -shape. - -.. code:: python - - >>> array41 = np.reshape([1, 2, 3, 4], (4,1)) - >>> array41 - array([[1], - [2], - [3], - [4]]) - >>> mapdl.parameters['mapdlarray41'] = array41 - >>> mapdl.parameters['mapdlarray41'] - array([[1.], - [2.], - [3.], - [4.]]) - >>> np.allclose(mapdl.parameters['mapdlarray40'], mapdl.parameters['mapdlarray41']) - True \ No newline at end of file diff --git a/src/ansys/mapdl/core/__init__.py b/src/ansys/mapdl/core/__init__.py index 9da868af7d..30c20e2c01 100644 --- a/src/ansys/mapdl/core/__init__.py +++ b/src/ansys/mapdl/core/__init__.py @@ -35,6 +35,7 @@ close_all_local_instances, find_ansys, get_ansys_path, + get_available_ansys_installations, save_ansys_path, ) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 1c2b7ec5aa..14f4ba92c7 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -619,18 +619,25 @@ def get_start_instance(start_instance_default=True): def _get_available_base_ansys(): - """Return a dictionary of available ANSYS versions with their base paths. + """Return a dictionary of available Ansys versions with their base paths. + + Notes + ----- + + On Windows, It uses the environment variable ``AWP_ROOTXXX``. + + The student versions are returned at the end of the dict and with negative value for the version. Returns ------- - Return all installed ANSYS paths in Windows + Return all installed Ansys paths in Windows. >>> _get_available_base_ansys() - {194: 'C:\\Program Files\\ANSYS INC\\v194', - 202: 'C:\\Program Files\\ANSYS INC\\v202', - 211: 'C:\\Program Files\\ANSYS INC\\v211'} + {222: 'C:\\Program Files\\ANSYS Inc\\v222', + 212: 'C:\\Program Files\\ANSYS Inc\\v212', + -222: 'C:\\Program Files\\ANSYS Inc\\ANSYS Student\\v222'} - Within Linux + Return all installed Ansys paths in Linux. >>> _get_available_base_ansys() {194: '/usr/ansys_inc/v194', @@ -702,6 +709,35 @@ def _get_available_base_ansys(): return ansys_paths +def get_available_ansys_installations(): + """Return a dictionary of available Ansys versions with their base paths. + + Notes + ----- + + On Windows, It uses the environment variable ``AWP_ROOTXXX``. + + The student versions are returned at the end of the dict and with negative value for the version. + + Returns + ------- + Return all installed Ansys paths in Windows. + + >>> get_available_ansys_installations() + {222: 'C:\\Program Files\\ANSYS Inc\\v222', + 212: 'C:\\Program Files\\ANSYS Inc\\v212', + -222: 'C:\\Program Files\\ANSYS Inc\\ANSYS Student\\v222'} + + Return all installed Ansys paths in Linux. + + >>> get_available_ansys_installations() + {194: '/usr/ansys_inc/v194', + 202: '/usr/ansys_inc/v202', + 211: '/usr/ansys_inc/v211'} + """ + return _get_available_base_ansys() + + def find_ansys(): """Searches for ansys path within the standard install location and returns the path of the latest version. diff --git a/tests/test_mapdl.py b/tests/test_mapdl.py index 389f59819e..b46ca98148 100644 --- a/tests/test_mapdl.py +++ b/tests/test_mapdl.py @@ -1532,6 +1532,21 @@ def test_lsread(mapdl, cleared): assert "No nodal" not in mapdl.flist() +def test_get_available_ansys_installations(): + from ansys.mapdl.core.launcher import ( + _get_available_base_ansys, + get_available_ansys_installations, + ) + + _get_doc = _get_available_base_ansys.__doc__ + get_doc = get_available_ansys_installations.__doc__ + + assert _get_doc == get_doc.replace( + "get_available_ansys_installations", "_get_available_base_ansys" + ) + assert _get_available_base_ansys() == get_available_ansys_installations() + + def test_get_fallback(mapdl, cleared): with pytest.raises(ValueError, match="There are no NODES defined"): mapdl.get_value("node", 0, "num", "maxd")