From fc26f9dc70c4d79ae3011507c618b9df650e8217 Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 19:31:37 +0100 Subject: [PATCH 01/16] Adding option to publish to dev from the CI before merging --- .github/workflows/ci.yml | 11 ++++++++--- .github/workflows/nightly-doc-build.yml | 2 +- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 28fb6a9873..85948c0244 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,6 +3,11 @@ name: CI on: pull_request: workflow_dispatch: + inputs: + test_dev_docs: + description: 'Publish the documentation before merging' + type: boolean + required: false push: tags: - "*" @@ -97,8 +102,8 @@ jobs: - name: "Install OS packages" run: | - sudo apt update - sudo apt install zip pandoc libgl1-mesa-glx xvfb texlive-latex-extra latexmk + sudo apt update + sudo apt install zip pandoc libgl1-mesa-glx xvfb texlive-latex-extra latexmk graphviz - name: "Cache pip" uses: actions/cache@v3 @@ -550,7 +555,7 @@ jobs: upload_dev_docs: name: "Upload dev documentation" - if: github.ref == 'refs/heads/main' + if: ${{ github.ref == 'refs/heads/main' || github.event.inputs.publish == 'true' }} runs-on: ubuntu-latest needs: [docs_build] steps: diff --git a/.github/workflows/nightly-doc-build.yml b/.github/workflows/nightly-doc-build.yml index 5b01b77e33..72b7168674 100644 --- a/.github/workflows/nightly-doc-build.yml +++ b/.github/workflows/nightly-doc-build.yml @@ -33,7 +33,7 @@ jobs: - name: Install OS packages run: | sudo apt-get update - sudo apt-get install libgl1-mesa-glx xvfb pandoc -qy + sudo apt-get install libgl1-mesa-glx xvfb pandoc graphviz -qy - name: Install ansys-mapdl-core run: | From 5ba6a412288c82319d60e8435377022b7121458f Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 19:32:26 +0100 Subject: [PATCH 02/16] Reorg in docs --- .../building_example.rst | 0 .../commands.rst | 0 .../database.rst | 0 .../geometry.rst | 0 .../{contribution_and_api => api}/helper.rst | 0 doc/source/api/index.rst | 38 ++++ .../{contribution_and_api => api}/inline.rst | 0 .../{contribution_and_api => api}/krylov.rst | 0 .../{contribution_and_api => api}/logging.rst | 0 .../{contribution_and_api => api}/mapdl.rst | 0 .../{contribution_and_api => api}/math.rst | 0 .../{contribution_and_api => api}/mesh.rst | 0 .../parameters.rst | 0 .../plotting.rst | 0 .../{contribution_and_api => api}/pool.rst | 0 .../{contribution_and_api => api}/post.rst | 0 .../solution.rst | 0 .../unit_testing.rst | 0 .../{contribution_and_api => api}/xpl.rst | 0 doc/source/conf.py | 6 + .../contribution.rst} | 43 +---- doc/source/getting_started/docker.rst | 138 ++++++++++++-- .../{troubleshoot => getting_started}/faq.rst | 0 doc/source/getting_started/index.rst | 8 +- .../learning.rst} | 0 doc/source/getting_started/running_mapdl.rst | 8 +- doc/source/getting_started/using_julia.rst | 6 +- doc/source/getting_started/versioning.rst | 3 +- doc/source/getting_started/wsl.rst | 92 ++------- doc/source/index.rst | 4 +- doc/source/troubleshoot/index.rst | 54 ------ doc/source/user_guide/index.rst | 1 + .../troubleshoot.rst | 180 +++++++++++------- 33 files changed, 318 insertions(+), 263 deletions(-) rename doc/source/{contribution_and_api => api}/building_example.rst (100%) rename doc/source/{contribution_and_api => api}/commands.rst (100%) rename doc/source/{contribution_and_api => api}/database.rst (100%) rename doc/source/{contribution_and_api => api}/geometry.rst (100%) rename doc/source/{contribution_and_api => api}/helper.rst (100%) create mode 100644 doc/source/api/index.rst rename doc/source/{contribution_and_api => api}/inline.rst (100%) rename doc/source/{contribution_and_api => api}/krylov.rst (100%) rename doc/source/{contribution_and_api => api}/logging.rst (100%) rename doc/source/{contribution_and_api => api}/mapdl.rst (100%) rename doc/source/{contribution_and_api => api}/math.rst (100%) rename doc/source/{contribution_and_api => api}/mesh.rst (100%) rename doc/source/{contribution_and_api => api}/parameters.rst (100%) rename doc/source/{contribution_and_api => api}/plotting.rst (100%) rename doc/source/{contribution_and_api => api}/pool.rst (100%) rename doc/source/{contribution_and_api => api}/post.rst (100%) rename doc/source/{contribution_and_api => api}/solution.rst (100%) rename doc/source/{contribution_and_api => api}/unit_testing.rst (100%) rename doc/source/{contribution_and_api => api}/xpl.rst (100%) rename doc/source/{contribution_and_api/index.rst => getting_started/contribution.rst} (79%) rename doc/source/{troubleshoot => getting_started}/faq.rst (100%) rename doc/source/{learning/index.rst => getting_started/learning.rst} (100%) delete mode 100644 doc/source/troubleshoot/index.rst rename doc/source/{troubleshoot => user_guide}/troubleshoot.rst (90%) diff --git a/doc/source/contribution_and_api/building_example.rst b/doc/source/api/building_example.rst similarity index 100% rename from doc/source/contribution_and_api/building_example.rst rename to doc/source/api/building_example.rst diff --git a/doc/source/contribution_and_api/commands.rst b/doc/source/api/commands.rst similarity index 100% rename from doc/source/contribution_and_api/commands.rst rename to doc/source/api/commands.rst diff --git a/doc/source/contribution_and_api/database.rst b/doc/source/api/database.rst similarity index 100% rename from doc/source/contribution_and_api/database.rst rename to doc/source/api/database.rst diff --git a/doc/source/contribution_and_api/geometry.rst b/doc/source/api/geometry.rst similarity index 100% rename from doc/source/contribution_and_api/geometry.rst rename to doc/source/api/geometry.rst diff --git a/doc/source/contribution_and_api/helper.rst b/doc/source/api/helper.rst similarity index 100% rename from doc/source/contribution_and_api/helper.rst rename to doc/source/api/helper.rst diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 0000000000..8642d79280 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,38 @@ + +.. _ref_index_api: + +API reference +============= + +This page gives an overview of the API of several public PyMAPDL +classes, functions, and attributes. You can find them +on the left sidebar. + +While these methods might include some MAPDL commands, they are generally +specific to PyMAPDL methods and classes. PyMAPDL methods extend existing +MAPDL methods in a Pythonic manner. For a mapping of MAPDL commands to +PyMAPDL, see :ref:`ref_mapdl_commands`. + + +.. toctree:: + :maxdepth: 2 + :hidden: + + commands + database + geometry + helper + inline + krylov + logging + mapdl + math + mesh + parameters + plotting + pool + post + solution + xpl + building_example + unit_testing diff --git a/doc/source/contribution_and_api/inline.rst b/doc/source/api/inline.rst similarity index 100% rename from doc/source/contribution_and_api/inline.rst rename to doc/source/api/inline.rst diff --git a/doc/source/contribution_and_api/krylov.rst b/doc/source/api/krylov.rst similarity index 100% rename from doc/source/contribution_and_api/krylov.rst rename to doc/source/api/krylov.rst diff --git a/doc/source/contribution_and_api/logging.rst b/doc/source/api/logging.rst similarity index 100% rename from doc/source/contribution_and_api/logging.rst rename to doc/source/api/logging.rst diff --git a/doc/source/contribution_and_api/mapdl.rst b/doc/source/api/mapdl.rst similarity index 100% rename from doc/source/contribution_and_api/mapdl.rst rename to doc/source/api/mapdl.rst diff --git a/doc/source/contribution_and_api/math.rst b/doc/source/api/math.rst similarity index 100% rename from doc/source/contribution_and_api/math.rst rename to doc/source/api/math.rst diff --git a/doc/source/contribution_and_api/mesh.rst b/doc/source/api/mesh.rst similarity index 100% rename from doc/source/contribution_and_api/mesh.rst rename to doc/source/api/mesh.rst diff --git a/doc/source/contribution_and_api/parameters.rst b/doc/source/api/parameters.rst similarity index 100% rename from doc/source/contribution_and_api/parameters.rst rename to doc/source/api/parameters.rst diff --git a/doc/source/contribution_and_api/plotting.rst b/doc/source/api/plotting.rst similarity index 100% rename from doc/source/contribution_and_api/plotting.rst rename to doc/source/api/plotting.rst diff --git a/doc/source/contribution_and_api/pool.rst b/doc/source/api/pool.rst similarity index 100% rename from doc/source/contribution_and_api/pool.rst rename to doc/source/api/pool.rst diff --git a/doc/source/contribution_and_api/post.rst b/doc/source/api/post.rst similarity index 100% rename from doc/source/contribution_and_api/post.rst rename to doc/source/api/post.rst diff --git a/doc/source/contribution_and_api/solution.rst b/doc/source/api/solution.rst similarity index 100% rename from doc/source/contribution_and_api/solution.rst rename to doc/source/api/solution.rst diff --git a/doc/source/contribution_and_api/unit_testing.rst b/doc/source/api/unit_testing.rst similarity index 100% rename from doc/source/contribution_and_api/unit_testing.rst rename to doc/source/api/unit_testing.rst diff --git a/doc/source/contribution_and_api/xpl.rst b/doc/source/api/xpl.rst similarity index 100% rename from doc/source/contribution_and_api/xpl.rst rename to doc/source/api/xpl.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 6e13d4c631..fbd239f1fc 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -63,6 +63,7 @@ "sphinx_copybutton", "sphinx_gallery.gen_gallery", "sphinxemoji.sphinxemoji", + "sphinx.ext.graphviz", ] # Intersphinx mapping @@ -205,6 +206,11 @@ "url": "https://github.com/pyansys/pymapdl/discussions", "icon": "fa fa-comment fa-fw", }, + { + "name": "Contribute", + "url": "https://mapdl.docs.pyansys.com/release/dev/getting_started/contribution.html", + "icon": "fa fa-wrench", + }, ], "switcher": { "json_url": f"https://{cname}/release/versions.json", diff --git a/doc/source/contribution_and_api/index.rst b/doc/source/getting_started/contribution.rst similarity index 79% rename from doc/source/contribution_and_api/index.rst rename to doc/source/getting_started/contribution.rst index 3e8e44de4f..ecf8d5e596 100644 --- a/doc/source/contribution_and_api/index.rst +++ b/doc/source/getting_started/contribution.rst @@ -1,8 +1,8 @@ .. _ref_contributing: -==================== -Contributing and API -==================== +============ +Contributing +============ Overall guidance on contributing to a PyAnsys library appears in the `Contributing `_ topic @@ -102,40 +102,3 @@ This way, it's not possible for you to push code that fails the style checks. Fo flake8...................................................................Passed codespell................................................................Passed - -.. _ref_index_api: - -API reference -============= -This page gives an overview of the API of several public PyMAPDL -classes, functions, and attributes. You can find them -on the left sidebar. - -While these methods might include some MAPDL commands, they are generally -specific to PyMAPDL methods and classes. PyMAPDL methods extend existing -MAPDL methods in a Pythonic manner. For a mapping of MAPDL commands to -PyMAPDL, see :ref:`ref_mapdl_commands`. - - -.. toctree:: - :maxdepth: 2 - :hidden: - - commands - database - geometry - helper - inline - krylov - logging - mapdl - math - mesh - parameters - plotting - pool - post - solution - xpl - building_example - unit_testing diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index d9ef9cc539..d186a05f04 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -1,7 +1,7 @@ .. _pymapdl_docker: ************************ -Use MAPDL through Docker +Docker Containers ************************ You can run MAPDL within a container on any OS using Docker and connect to it via PyMAPDL. @@ -17,7 +17,9 @@ in a containerized environment such as Docker or Singularity: Configure the Docker registry ============================= -There is a Docker image hosted on the +**Only for images in private repositories.** + +There are several Docker images hosted on the `PyMAPDL GitHub `_ repository that you can download using your GitHub credentials. @@ -47,18 +49,34 @@ Run an MAPDL image =================== You can now launch MAPDL directly from Docker with a short script or -directly from the command line. Because this image contains no license -server, you must enter your license server IP address in the -``LICENSE_SERVER`` environment variable. With that, you can launch -MAPDL with: +directly from the command line. +You can use then your host python environment to connect to that MAPDL +instance. + +.. graphviz:: + + digraph { + node []; + subgraph cluster_frontend { + label="*HOST*"; + Python; + subgraph cluster_backend { + MAPDL; + label="*DOCKER*"; + } + } + Python -> MAPDL + MAPDL -> Python + } + +Because this image contains no license server, you must enter your +license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable. + +Additionally, you run a Docker image of PyMAPDL with: -.. code:: +.. code:: pwsh - LICENSE_SERVER=1055@XXX.XXX.XXX.XXX - VERSION=v21.1.0 - - IMAGE=ghcr.io/pyansys/pymapdl/mapdl:$VERSION - docker run -e ANSYSLMD_LICENSE_FILE=$LICENSE_SERVER -p 50052:50052 $IMAGE -smp + docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt First time you run it, Docker logins into the *ghcr.io* registry and pulls the image which can take some time. @@ -66,16 +84,39 @@ There are several images in the registry, each corresponding to a different version of MAPDL. It is recommended to use the latest version of MAPDL for the Ubuntu systems (any image tagged as ``Ubuntu``). -Note that port `50052` (local to the container) is being mapped to -50052 on the host. This makes it possible to launch several MAPDL -instances with different port mappings to allow for multiple instances -of MAPDL. +Successive runs should restart the container or just delete it and rerun it using: + +.. code:: pwsh + + docker stop mapdl + docker container prune + + docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt + +You can use the docker flag ``--rm`` to automatically clean up the container +and remove the file system when the container exits + +This creates a log file (``log.txt``) in your current directory location. + +Notice that the WSL internal gRPC port (``50052``) is being mapped to a +different Windows host port (``50053``) to avoid ports conflicts with local +MAPDL instances running on the host. +You could Additionally launch more docker containers in different ports if +you wish to run multiple simulations at the same time. +The module ``ansys-mapdl-core-pool`` does not work when you are connecting +to an MAPDL docker image. + +.. note:: Ensure that your port ``50053`` is open in your firewall. You can provide additional command line parameters to MAPDL by simply appending to the Docker command. For example, you can increase the number of processors (up to the number available on the host machine) with the `-np` switch. +You should use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``) +to run the preceding commands all at once. + + Once you have launched MAPDL you should see: .. code:: @@ -90,6 +131,7 @@ Once you have launched MAPDL you should see: Server listening on : 0.0.0.0:50052 + Using ``docker-compose`` to launch MAPDL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -138,6 +180,9 @@ use: If you would like to have access to it, please contact PyAnsys support at `pyansys.support@ansys.com `_. + +.. _pymapdl_connect_to_MAPDL_container: + Connect to the MAPDL container from Python ========================================== @@ -165,6 +210,67 @@ Verify your connection with: MAPDL Version: RELEASE 2021 R1 BUILD 21.0 PyMAPDL Version: Version: 0.57.0 + +You can also use :func:`launch_mapdl() ` to connect +to an existing MAPDL instance by using the argument ``start_instance=False``: + +.. code:: python + + from ansys.mapdl.core import launch_mapdl + + mapdl = launch_mapdl(port=50053, start_instance=False) + + +Because of the linking between host ports and docker ports (``-p`` argument), +you do not need to specify the IP when connecting to a local container. +However, if you are trying to connect to a WSL local distribution you need +to specify the IP address of the WSL instance (normally ``127.0.0.1``) since +no port mapping is done between both. +For example: + +.. code:: python + + from ansys.mapdl.core import Mapdl + + mapdl = Mapdl(ip='127.0.0.1', port=50053) + + +You can also specify the port and IP address using environment variables that are read when +launching the MAPDL instance: + +.. code:: bash + + export PYMAPDL_START_INSTANCE=False + export PYMAPDL_PORT=50053 + export PYMAPDL_IP=127.0.0.1 + + + +Launch Docker with UPF capabilities +=================================== + +If you want to specify a custom Python UPF routine, you must have the +environment variables ``ANS_USER_PATH`` and ``ANS_USE_UPF`` defined. The +former should be equal to the path where the UPF routines are located, and the +latter should be equal to ``TRUE``. + +In WSL, you can do this using: + +.. code:: bash + + export ANS_USER_PATH=/home/user/UPFs # Use your own path to your UPF files. + export ANS_USE_UPF=TRUE + +You can then run the Docker image with: + +.. code:: bash + + docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal -e ANS_USER_PATH='/ansys_jobs/upf' -e ANS_USE_UPF='TRUE' --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp 1>log.txt + +.. warning:: The use of UPFs with Docker images or PyMAPDL is still in the alpha state. + + + Additional considerations ========================= diff --git a/doc/source/troubleshoot/faq.rst b/doc/source/getting_started/faq.rst similarity index 100% rename from doc/source/troubleshoot/faq.rst rename to doc/source/getting_started/faq.rst diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 15fc1d96c1..692a97b73f 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -13,11 +13,15 @@ For more information on getting a licensed copy of Ansys, visit :hidden: :maxdepth: 2 - running_mapdl + learning versioning + running_mapdl docker - using_julia wsl + using_julia + faq + contribution + ************ Installation diff --git a/doc/source/learning/index.rst b/doc/source/getting_started/learning.rst similarity index 100% rename from doc/source/learning/index.rst rename to doc/source/getting_started/learning.rst diff --git a/doc/source/getting_started/running_mapdl.rst b/doc/source/getting_started/running_mapdl.rst index 4f5ae3590c..e90d84d2b2 100644 --- a/doc/source/getting_started/running_mapdl.rst +++ b/doc/source/getting_started/running_mapdl.rst @@ -1,8 +1,8 @@ .. _using_standard_install: -****************************************** -Use PyMAPDL from the standard installation -****************************************** +********************* +Standard installation +********************* The PyAnsys ``ansys-mapdl-core`` package requires either a local or remote instance of MAPDL to communicate with it. This section covers @@ -58,6 +58,8 @@ automatically connect to it: This is the easiest and fastest way to get PyMAPDL up and running. But you need to have an ANSYS license server installed locally. +.. _launch_grpc_madpl_session: + Launch a gRPC MAPDL session ~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can start MAPDL from the command line and then connect to it. diff --git a/doc/source/getting_started/using_julia.rst b/doc/source/getting_started/using_julia.rst index 6c631bb4de..3fc37792fe 100644 --- a/doc/source/getting_started/using_julia.rst +++ b/doc/source/getting_started/using_julia.rst @@ -1,9 +1,9 @@ .. _using_julia: -******************** -Use PyMAPDL in Julia -******************** +***************** +Julia and PyMAPDL +***************** If you like to work with Julia, you can use Python libraries as if they were Julia packages. diff --git a/doc/source/getting_started/versioning.rst b/doc/source/getting_started/versioning.rst index 0e869d79d5..87c6b54363 100644 --- a/doc/source/getting_started/versioning.rst +++ b/doc/source/getting_started/versioning.rst @@ -1,6 +1,7 @@ *********************** Versions and interfaces *********************** + The PyMAPDL project attempts to maintain compatibility with legacy versions of MAPDL while allowing for support of faster and better interfaces with the latest versions of MAPDL. @@ -8,13 +9,13 @@ interfaces with the latest versions of MAPDL. There are three interfaces PyMAPDL can use to connect to MAPDL. - gRPC interface ~~~~~~~~~~~~~~ This is the default and preferred interface to connect to MAPDL. Ansys 2020 R1 and later support the latest `gRPC interface `_, allowing for remote management of MAPDL with rapid streaming of mesh, results, and files from the MAPDL service. + This interface also allows to work with a Docker image. If you have the applicable license, you can install and use MAPDL within Docker, enabling you diff --git a/doc/source/getting_started/wsl.rst b/doc/source/getting_started/wsl.rst index 84ced0342b..1455980588 100644 --- a/doc/source/getting_started/wsl.rst +++ b/doc/source/getting_started/wsl.rst @@ -1,8 +1,8 @@ .. _ref_guide_wsl: -PyAnsys libraries on a Windows Subsystem for Linux and Docker -############################################################# +Windows Subsystem for Linux +########################### This page shows you how to use a PyAnsys library, more specifically PyMAPDL, in the Windows Subsystem for Linux (WSL). WSL is a compatibility layer for @@ -132,7 +132,7 @@ This works if you want to run a Docker image using WSL Linux image to host that Docker image. The Docker image successfully communicates with the Windows License Server using these ports if you use the ``'-p'`` flag when running the Docker image and these ports are open. -See `Run MAPDL on a local Docker image`_. +See `Run an MAPDL image`_. If you want to run MAPDL in the CentOS 7 image and use the Windows license @@ -199,49 +199,31 @@ environment variable with this IP address: .. vale off +Launch MAPDL in WSL +=================== -Run MAPDL on a local Docker image -********************************* - -To run a Docker image, you must follow all steps in `Run PyMAPDL on WSL`_ . - -Additionally, you run a Docker image of PyMAPDL with: - -.. code:: pwsh - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt - -Successive runs should restart the container or just delete it and rerun it using: - -.. code:: pwsh - - docker stop mapdl - docker container prune - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt - - -This creates a log file (``log.txt``) in your current directory location. - +To launch MAPDL in WSL, you need to do as in +`Launch a gRPC MAPDL session `. +For example: -.. note:: Ensure that your port ``50053`` is open in your firewall. +.. code:: bash -You should use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``) -to run the preceding commands all at once. + /ansys_inc/v222/ansys/bin/ansys222 -grpc -Notice that the WSL internal gRPC port (``50052``) is being mapped to a -different Windows host port (``50053``) to avoid ports conflicts. +This launches an MAPDL instance whose working directory is the current directory. +If you want to change the working directory, you can use the ``-dir`` flag. -This image is ready to be connected to from WSL or Windows Host but the port -and IP should be specified as: -.. code:: python +.. code:: bash - from ansys.mapdl.core import launch_mapdl + /ansys_inc/v222/ansys/bin/ansys222 -grpc -dir /tmp/ansys_jobs/myjob - mapdl = launch_mapdl(ip='127.0.0.1', port=50053, start_instance=False) +Connect to an MAPDL instance running in WSL +=========================================== -Or: +To connect to the WSL instance which is running the MAPDL instance follow the +instructions given in `Connect to the MAPDL container from Python`_ but specifying +the IP address of the WSL instance. For example: .. code:: python @@ -250,44 +232,10 @@ Or: mapdl = Mapdl(ip='127.0.0.1', port=50053) -You can also specify the port and IP address using environment variables that are read when -launching the MAPDL instance: - -.. code:: bash - - export PYMAPDL_START_INSTANCE=False - export PYMAPDL_PORT=50053 - export PYMAPDL_IP=127.0.0.1 - - -Launch Docker with UPF capabilities -=================================== - -If you want to specify a custom Python UPF routine, you must have the -environment variables ``ANS_USER_PATH`` and ``ANS_USE_UPF`` defined. The -former should be equal to the path where the UPF routines are located, and the -latter should be equal to ``TRUE``. - -In WSL, you can do this using: - -.. code:: bash - - export ANS_USER_PATH=/home/user/UPFs # Use your own path to your UPF files. - export ANS_USE_UPF=TRUE - -You can then run the Docker image with: - -.. code:: bash - - docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal -e ANS_USER_PATH='/ansys_jobs/upf' -e ANS_USE_UPF='TRUE' --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp 1>log.txt - -.. warning:: The use of UPFs with Docker images or PyMAPDL is still in the alpha state. - - Notes ===== -The specified IP address ``127.0.0.1`` in `Run MAPDL on a local Docker image`_ is +The specified IP address ``127.0.0.1`` in `Run an MAPDL image`_ is the IP address of WSL CentOS from the WSL perspective, whereas the Windows host IP address is normally ``127.0.1.1``. Docker builds the PyMAPDL images using the WSL distribution as the base. Hence, PyMAPDL is running on a Linux WSL diff --git a/doc/source/index.rst b/doc/source/index.rst index 8f1e0312ad..f2d988ee99 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,10 +8,8 @@ PyMAPDL documentation |version| getting_started/index user_guide/index mapdl_commands/index + api/index examples/index - learning/index - troubleshoot/index - contribution_and_api/index diff --git a/doc/source/troubleshoot/index.rst b/doc/source/troubleshoot/index.rst deleted file mode 100644 index 7453f931da..0000000000 --- a/doc/source/troubleshoot/index.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _ref_troubleshooting: - -=============== -Troubleshooting -=============== - -To help overcome any problem that you might have when using PyMAPDL, -some of the most common problems and frequently asked questions are posted here. - - -.. toctree:: - :maxdepth: 3 - - troubleshoot - faq - - -Debug in PyMAPDL ----------------- - -If you are having trouble with PyMAPDL, you can examine the content -of the output file to help to identify any issue. - -You can set the logger output file to be ``mylog.log`` by -running the following commands in a Python terminal or at the beginning of your -script: - -.. code:: python - - from ansys.mapdl.core import LOG - LOG.setLevel("DEBUG") - LOG.log_to_file("mylog.log") - - from ansys.mapdl.core import launch_mapdl - - mapdl = launch_mapdl(loglevel="DEBUG") - -You can attach this file to a bug report in the PyMAPDL GitHub repository for further investigation. -If you are not able to identify the issue, you can open a discussion on the -`PyMAPDL Discussions page `_. -If you believe you have found a bug, open an issue on the -`PyMAPDL Issues page `_. - - - -More help needed? ------------------ - - *"What do you do if a problem is not listed here?"* - -You can go to `PyMAPDL Repository Discussion `_ and ask about it. - -If you think you found a bug or would like to make a feature request, you can do so by -opening an issue in `PyMAPDL Repository Issues `_. \ No newline at end of file diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index f4cbd55240..b00b0cc543 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -28,6 +28,7 @@ This section provides a general overview of PyMAPDL and how you use it. xpl upf krylov + troubleshoot PyMAPDL overview diff --git a/doc/source/troubleshoot/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst similarity index 90% rename from doc/source/troubleshoot/troubleshoot.rst rename to doc/source/user_guide/troubleshoot.rst index 60eb77a22e..b96a127ef9 100644 --- a/doc/source/troubleshoot/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -1,22 +1,71 @@ -.. _debugging_launch_mapdl: + +.. _ref_troubleshooting: + ======================= Troubleshooting PyMAPDL ======================= +To help overcome any problem that you might have when using PyMAPDL, +some of the most common problems and frequently asked questions are posted here. + + ***************** -Launching MAPDL +Debug in PyMAPDL ***************** -For any number of reasons, Python may fail to launch MAPDL. Here are -some approaches for debugging: +If you are having trouble with PyMAPDL, you can record some internal +logs into a file using a logger. +This file can be examined to help to identify any issue. + +You can set the logger output file to be ``mylog.log`` by +running the following commands in a Python terminal or at the beginning of your +script: + +.. code:: python + + from ansys.mapdl.core import LOG + LOG.setLevel("DEBUG") + LOG.log_to_file("mylog.log") + + from ansys.mapdl.core import launch_mapdl + + mapdl = launch_mapdl(loglevel="DEBUG") + +You can attach this file to a bug report in the PyMAPDL GitHub repository for further investigation. +If you are not able to identify the issue, you can open a discussion on the +`PyMAPDL Discussions page `_. +If you believe you have found a bug, open an issue on the +`PyMAPDL Issues page `_. + + +.. _debugging_launch_mapdl: + +**************** +Launching issues +**************** + +There are several issues that can cause MAPDL not to launch, including: + +- `Licensing issues`_ +- `Virtual private network (VPN) issues`_ +- `Missing dependencies on Linux`_ +- `Conflicts with student version`_ +- `Incorrect environment variables`_ +- `Using a proxy server`_ +- `Firewall settings`_ + + +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: @@ -28,7 +77,8 @@ Open up a command prompt and run the version-dependent command: PowerShell users can run the preceding command without quotes. -**On Linux** +On Linux +-------- Run the version-dependent command: @@ -67,17 +117,6 @@ If this command doesn't launch MAPDL, look at the command output: variable to OFF. -There are many issues that can cause MAPDL not to launch, including: - -- `Licensing issues`_ -- `Virtual private network (VPN) issues`_ -- `Missing dependencies on Linux`_ -- `Conflicts with student version`_ -- `Incorrect environment variables`_ -- `Using a proxy server`_ -- `Firewall settings`_ - - Licensing issues ================ @@ -346,14 +385,6 @@ For more information on how to **configure your firewall on Ubuntu Linux**, plea link `Security-Firewall | Ubuntu `_. -***************** -Launching PyMAPDL -***************** - -Even if you are able to successfully launch MAPDL, PyMAPDL itself might not launch -successfully. - - Manually set the location of the executable file ================================================ If you have a non-standard install, PyMAPDL might be unable find @@ -379,7 +410,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. @@ -449,50 +480,11 @@ method lists higher versions first and student versions last. 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 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 you can turn on or turn off logging and - verbosity when 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 - :func:`Mapdl.eread() ` methods. - - - - - .. _ref_pymapdl_limitations: -******************* -PyMAPDL limitations -******************* - +********************* +PyMAPDL Usage issues +********************* .. _ref_numpy_arrays_in_mapdl: @@ -548,4 +540,54 @@ to one, have the same shape if later retrieved. [3.], [4.]]) >>> np.allclose(mapdl.parameters['mapdlarray'], mapdl.parameters['mapdlarray_b']) - True \ No newline at end of file + 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 performance and stability of MADPL: + +- 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 + your program or script so you can turn on or turn off logging and + verbosity when 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 + :func:`Mapdl.eread() ` methods. + + + +More help needed? +----------------- + + *"What do you do if a problem is not listed here?"* + + +You can check if there is an issue already tracking your problem in `PyMAPDL Repository Issues `_. + +You can go to `PyMAPDL Repository Discussion `_ and ask about it. + +If you think you found a bug or would like to make a feature request, you can do so by +opening an feature request in `PyMAPDL Repository Issues `_. \ No newline at end of file From ac74e14ec596c9fcf391b8d34e26b505e196f4e9 Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 19:49:20 +0100 Subject: [PATCH 03/16] Fixing vale --- doc/source/getting_started/docker.rst | 16 ++++++++-------- doc/source/user_guide/troubleshoot.rst | 12 ++++++------ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index d186a05f04..6b4909a753 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -1,8 +1,8 @@ .. _pymapdl_docker: -************************ -Docker Containers -************************ +***************** +Docker containers +***************** You can run MAPDL within a container on any OS using Docker and connect to it via PyMAPDL. @@ -50,7 +50,7 @@ Run an MAPDL image You can now launch MAPDL directly from Docker with a short script or directly from the command line. -You can use then your host python environment to connect to that MAPDL +You can use then your host Python environment to connect to that MAPDL instance. .. graphviz:: @@ -93,7 +93,7 @@ Successive runs should restart the container or just delete it and rerun it usin docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt -You can use the docker flag ``--rm`` to automatically clean up the container +You can use the Docker flag ``--rm`` to automatically clean up the container and remove the file system when the container exits This creates a log file (``log.txt``) in your current directory location. @@ -101,10 +101,10 @@ This creates a log file (``log.txt``) in your current directory location. Notice that the WSL internal gRPC port (``50052``) is being mapped to a different Windows host port (``50053``) to avoid ports conflicts with local MAPDL instances running on the host. -You could Additionally launch more docker containers in different ports if +You could additionally launch more Docker containers in different ports if you wish to run multiple simulations at the same time. The module ``ansys-mapdl-core-pool`` does not work when you are connecting -to an MAPDL docker image. +to an MAPDL Docker image. .. note:: Ensure that your port ``50053`` is open in your firewall. @@ -221,7 +221,7 @@ to an existing MAPDL instance by using the argument ``start_instance=False``: mapdl = launch_mapdl(port=50053, start_instance=False) -Because of the linking between host ports and docker ports (``-p`` argument), +Because of the linking between host ports and Docker ports (``-p`` argument), you do not need to specify the IP when connecting to a local container. However, if you are trying to connect to a WSL local distribution you need to specify the IP address of the WSL instance (normally ``127.0.0.1``) since diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index b96a127ef9..fddab90034 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -483,7 +483,7 @@ method lists higher versions first and student versions last. .. _ref_pymapdl_limitations: ********************* -PyMAPDL Usage issues +PyMAPDL usage issues ********************* .. _ref_numpy_arrays_in_mapdl: @@ -585,9 +585,9 @@ More help needed? *"What do you do if a problem is not listed here?"* -You can check if there is an issue already tracking your problem in `PyMAPDL Repository Issues `_. +Visit `PyMAPDL Repository Issues `_ and search if your issue is already listed. +If not, you can do one of the following: -You can go to `PyMAPDL Repository Discussion `_ and ask about it. - -If you think you found a bug or would like to make a feature request, you can do so by -opening an feature request in `PyMAPDL Repository Issues `_. \ No newline at end of file +* Go to `PyMAPDL Repository Discussion `_ and create a discussion about your issue. +* If you think you found a bug or would like to make a feature request, you can do so by +opening an feature request in `PyMAPDL Repository Issues `_. From 13ed81e852775ee23bba38cfb78bd68bee819753 Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 20:15:13 +0100 Subject: [PATCH 04/16] Resetting cache --- .github/workflows/ci.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 85948c0244..1a6a14b5a5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,10 +31,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: 2 - RESET_EXAMPLES_CACHE: 2 - RESET_DOC_BUILD_CACHE: 2 - RESET_AUTOSUMMARY_CACHE: 2 + RESET_PIP_CACHE: 0 + RESET_EXAMPLES_CACHE: 0 + RESET_DOC_BUILD_CACHE: 0 + RESET_AUTOSUMMARY_CACHE: 0 concurrency: group: ${{ github.workflow }}-${{ github.ref }} From e416da7ac4683dd25ee23786143df989fd05b4ec Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 20:40:24 +0100 Subject: [PATCH 05/16] Fixing doc building warnings. --- doc/source/getting_started/docker.rst | 2 ++ doc/source/getting_started/wsl.rst | 9 +++++---- doc/source/user_guide/troubleshoot.rst | 14 +++++++++----- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index 6b4909a753..c4c921dbfc 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -45,6 +45,8 @@ with: cat GH_TOKEN.txt | docker login ghcr.io -u $GH_USERNAME --password-stdin +.. _run_an_mapdl_image: + Run an MAPDL image =================== diff --git a/doc/source/getting_started/wsl.rst b/doc/source/getting_started/wsl.rst index 1455980588..f6b0138d84 100644 --- a/doc/source/getting_started/wsl.rst +++ b/doc/source/getting_started/wsl.rst @@ -132,7 +132,7 @@ This works if you want to run a Docker image using WSL Linux image to host that Docker image. The Docker image successfully communicates with the Windows License Server using these ports if you use the ``'-p'`` flag when running the Docker image and these ports are open. -See `Run an MAPDL image`_. +See `Run an MAPDL image `_. If you want to run MAPDL in the CentOS 7 image and use the Windows license @@ -222,8 +222,9 @@ Connect to an MAPDL instance running in WSL =========================================== To connect to the WSL instance which is running the MAPDL instance follow the -instructions given in `Connect to the MAPDL container from Python`_ but specifying -the IP address of the WSL instance. For example: +instructions given in +`Connect to the MAPDL container from Python `_ +but specifying the IP address of the WSL instance. For example: .. code:: python @@ -235,7 +236,7 @@ the IP address of the WSL instance. For example: Notes ===== -The specified IP address ``127.0.0.1`` in `Run an MAPDL image`_ is +The specified IP address ``127.0.0.1`` in `Run an MAPDL image `_ is the IP address of WSL CentOS from the WSL perspective, whereas the Windows host IP address is normally ``127.0.1.1``. Docker builds the PyMAPDL images using the WSL distribution as the base. Hence, PyMAPDL is running on a Linux WSL diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index fddab90034..e538612259 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -585,9 +585,13 @@ More help needed? *"What do you do if a problem is not listed here?"* -Visit `PyMAPDL Repository Issues `_ and search if your issue is already listed. -If not, you can do one of the following: +Visit `PyMAPDL Repository Issues `_ and search if your +issue is already listed. If not, you can do one of the following: + +* Go to `PyMAPDL Repository Discussion `_ and + create a discussion about your issue. + +* If you think you found a bug or would like to make a feature request, + you can do so by opening an feature request in + `PyMAPDL Repository Issues `_. -* Go to `PyMAPDL Repository Discussion `_ and create a discussion about your issue. -* If you think you found a bug or would like to make a feature request, you can do so by -opening an feature request in `PyMAPDL Repository Issues `_. From 9a9da63c2b391d41d5161c3151c72615ae9fd70e Mon Sep 17 00:00:00 2001 From: German Date: Tue, 13 Dec 2022 21:54:24 +0100 Subject: [PATCH 06/16] fixing links --- doc/source/getting_started/wsl.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/getting_started/wsl.rst b/doc/source/getting_started/wsl.rst index f6b0138d84..58cb600345 100644 --- a/doc/source/getting_started/wsl.rst +++ b/doc/source/getting_started/wsl.rst @@ -132,7 +132,7 @@ This works if you want to run a Docker image using WSL Linux image to host that Docker image. The Docker image successfully communicates with the Windows License Server using these ports if you use the ``'-p'`` flag when running the Docker image and these ports are open. -See `Run an MAPDL image `_. +See `Run an MAPDL image `. If you want to run MAPDL in the CentOS 7 image and use the Windows license @@ -223,7 +223,7 @@ Connect to an MAPDL instance running in WSL To connect to the WSL instance which is running the MAPDL instance follow the instructions given in -`Connect to the MAPDL container from Python `_ +`Connect to the MAPDL container from Python ` but specifying the IP address of the WSL instance. For example: .. code:: python @@ -236,7 +236,7 @@ but specifying the IP address of the WSL instance. For example: Notes ===== -The specified IP address ``127.0.0.1`` in `Run an MAPDL image `_ is +The specified IP address ``127.0.0.1`` in `Run an MAPDL image ` is the IP address of WSL CentOS from the WSL perspective, whereas the Windows host IP address is normally ``127.0.1.1``. Docker builds the PyMAPDL images using the WSL distribution as the base. Hence, PyMAPDL is running on a Linux WSL From 8a36d9f0670972e7e3ba70a89a971148089df394 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 14 Dec 2022 10:26:09 +0100 Subject: [PATCH 07/16] Apply suggestions from code review Co-authored-by: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> --- doc/source/user_guide/troubleshoot.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index e538612259..3fc8cfb53c 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -591,7 +591,7 @@ issue is already listed. If not, you can do one of the following: * Go to `PyMAPDL Repository Discussion `_ and create a discussion about your issue. -* If you think you found a bug or would like to make a feature request, - you can do so by opening an feature request in +* If you found a bug or you want to make a feature request, + you can open a feature request in `PyMAPDL Repository Issues `_. From c11a9e49f767de4d56c31650dda6cb3efbdae190 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 14 Dec 2022 17:12:32 +0100 Subject: [PATCH 08/16] Apply suggestions from code review from Kathy Thank you a lot Kathy! Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/getting_started/docker.rst | 34 +++++++++++++------------- doc/source/getting_started/wsl.rst | 12 ++++----- doc/source/user_guide/troubleshoot.rst | 18 +++++++------- 3 files changed, 32 insertions(+), 32 deletions(-) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index c4c921dbfc..29032dcbde 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -52,7 +52,7 @@ Run an MAPDL image You can now launch MAPDL directly from Docker with a short script or directly from the command line. -You can use then your host Python environment to connect to that MAPDL +You can then use your host Python environment to connect to that MAPDL instance. .. graphviz:: @@ -71,7 +71,7 @@ instance. MAPDL -> Python } -Because this image contains no license server, you must enter your +Because this image does not contain a license server, you must enter your license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable. Additionally, you run a Docker image of PyMAPDL with: @@ -81,12 +81,12 @@ Additionally, you run a Docker image of PyMAPDL with: docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt First time you run it, Docker logins into the *ghcr.io* registry and -pulls the image which can take some time. +pulls the image, which can take some time. There are several images in the registry, each corresponding to a different -version of MAPDL. It is recommended to use the latest version of MAPDL for -the Ubuntu systems (any image tagged as ``Ubuntu``). +version of MAPDL. For Ubuntu systems (any image tagged as ``Ubuntu``), you should +use the latest version of MAPDL. -Successive runs should restart the container or just delete it and rerun it using: +To rerun it again, you should restart the container or just delete it and run it again using: .. code:: pwsh @@ -96,15 +96,15 @@ Successive runs should restart the container or just delete it and rerun it usin docker run -e ANSYSLMD_LICENSE_FILE=1055@host.docker.internal --restart always --name mapdl -p 50053:50052 ghcr.io/pyansys/pymapdl/mapdl -smp > log.txt You can use the Docker flag ``--rm`` to automatically clean up the container -and remove the file system when the container exits +and remove the file system when the container exits. This creates a log file (``log.txt``) in your current directory location. Notice that the WSL internal gRPC port (``50052``) is being mapped to a -different Windows host port (``50053``) to avoid ports conflicts with local +different Windows host port (``50053``) to avoid port conflicts with local MAPDL instances running on the host. You could additionally launch more Docker containers in different ports if -you wish to run multiple simulations at the same time. +you want to run multiple simulations at the same time. The module ``ansys-mapdl-core-pool`` does not work when you are connecting to an MAPDL Docker image. @@ -113,7 +113,7 @@ to an MAPDL Docker image. You can provide additional command line parameters to MAPDL by simply appending to the Docker command. For example, you can increase the number of processors (up to the -number available on the host machine) with the `-np` switch. +number available on the host machine) with the ``-np`` switch. You should use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``) to run the preceding commands all at once. @@ -179,7 +179,7 @@ use: The license server is not intended to be used in production. It is only intended for testing/debugging purposes. Its access is limited to collaborators of the PyAnsys project. - If you would like to have access to it, please contact PyAnsys support at + If you would like to have access to the license server, contact PyAnsys support at `pyansys.support@ansys.com `_. @@ -213,8 +213,7 @@ Verify your connection with: PyMAPDL Version: Version: 0.57.0 -You can also use :func:`launch_mapdl() ` to connect -to an existing MAPDL instance by using the argument ``start_instance=False``: +To connect to an existing MAPDL instance, you can use the :func:`launch_mapdl() ` method with the argument ``start_instance=False``: .. code:: python @@ -224,11 +223,12 @@ to an existing MAPDL instance by using the argument ``start_instance=False``: Because of the linking between host ports and Docker ports (``-p`` argument), -you do not need to specify the IP when connecting to a local container. -However, if you are trying to connect to a WSL local distribution you need -to specify the IP address of the WSL instance (normally ``127.0.0.1``) since +you do not need to specify the IP address when connecting to a local container. +However, if you are trying to connect to a WSL local distribution, you must +specify the IP address of the WSL instance (normally ``127.0.0.1``) because no port mapping is done between both. -For example: + +Here is an example: .. code:: python diff --git a/doc/source/getting_started/wsl.rst b/doc/source/getting_started/wsl.rst index 58cb600345..3ce8ca96ad 100644 --- a/doc/source/getting_started/wsl.rst +++ b/doc/source/getting_started/wsl.rst @@ -132,7 +132,7 @@ This works if you want to run a Docker image using WSL Linux image to host that Docker image. The Docker image successfully communicates with the Windows License Server using these ports if you use the ``'-p'`` flag when running the Docker image and these ports are open. -See `Run an MAPDL image `. +For more information, see `Run an MAPDL image `. If you want to run MAPDL in the CentOS 7 image and use the Windows license @@ -202,9 +202,9 @@ environment variable with this IP address: Launch MAPDL in WSL =================== -To launch MAPDL in WSL, you need to do as in +To launch MAPDL in WSL, you must follow the procedure in `Launch a gRPC MAPDL session `. -For example: +An example follows. .. code:: bash @@ -221,10 +221,10 @@ If you want to change the working directory, you can use the ``-dir`` flag. Connect to an MAPDL instance running in WSL =========================================== -To connect to the WSL instance which is running the MAPDL instance follow the -instructions given in +To connect to the WSL instance that is running the MAPDL instance, follow the +procedure in `Connect to the MAPDL container from Python ` -but specifying the IP address of the WSL instance. For example: +but specify the IP address of the WSL instance: .. code:: python diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 3fc8cfb53c..e7cebb8c67 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -9,7 +9,7 @@ Troubleshooting PyMAPDL ======================= -To help overcome any problem that you might have when using PyMAPDL, +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. @@ -555,15 +555,15 @@ 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: +are several ways to improve MADPL performance and 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 - your program or script so you can turn on or turn off logging and - verbosity when needed. + your program or script so that you can turn on and off logging and + verbosity as needed. Issues @@ -585,13 +585,13 @@ More help needed? *"What do you do if a problem is not listed here?"* -Visit `PyMAPDL Repository Issues `_ and search if your +Go to the `PyMAPDL Issues `_ page and search to see if your issue is already listed. If not, you can do one of the following: -* Go to `PyMAPDL Repository Discussion `_ and +* Go to the `PyMAPDL Discussions `_ page and create a discussion about your issue. -* If you found a bug or you want to make a feature request, - you can open a feature request in - `PyMAPDL Repository Issues `_. +* Go to the `PyMAPDL Issues `_ if you have found a bug + or want to create a feature request. + . From 2b515c678f91a1cf303965c50469fee669cc7734 Mon Sep 17 00:00:00 2001 From: German Date: Wed, 14 Dec 2022 17:20:08 +0100 Subject: [PATCH 09/16] Disabling Windows tests. --- .github/workflows/ci.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 54c593d9be..f8b936f77c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -508,15 +508,15 @@ jobs: # docker pull ghcr.io/pyansys/dpf-core:22.2dev # docker run -d --name dpfserver -p ${{ env.DPF_PORT }}:50052 ghcr.io/pyansys/dpf-core:22.2dev && echo "DPF Server active on port ${{ env.DPF_PORT }}." - - name: "Unit testing" - shell: powershell - run: | - set PYMAPDL_PORT= - set PYMAPDL_START_INSTANCE= - python -m pytest -v -k "not test_database and not test_dpf" --durations=10 --maxfail=10 --reruns 7 --reruns-delay 3 --only-rerun MapdlExitedError --only-rerun EmptyRecordError --cov=ansys.mapdl.core --cov-report=xml --cov-report=html + # - name: "Unit testing" + # shell: powershell + # run: | + # set PYMAPDL_PORT= + # set PYMAPDL_START_INSTANCE= + # python -m pytest -v -k "not test_database and not test_dpf" --durations=10 --maxfail=10 --reruns 7 --reruns-delay 3 --only-rerun MapdlExitedError --only-rerun EmptyRecordError --cov=ansys.mapdl.core --cov-report=xml --cov-report=html - - uses: codecov/codecov-action@v3 - name: "Upload coverage to Codecov" + # - uses: codecov/codecov-action@v3 + # name: "Upload coverage to Codecov" release: if: github.event_name == 'push' && contains(github.ref, 'refs/tags') From 55a3e7144e9572b01233f2c97ea36af228fa6220 Mon Sep 17 00:00:00 2001 From: German Date: Wed, 14 Dec 2022 17:23:24 +0100 Subject: [PATCH 10/16] Using an if instead of comments --- .github/workflows/ci.yml | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f8b936f77c..ccdd46daeb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -466,6 +466,7 @@ jobs: root_dir: ${{ github.workspace }} test_windows: + if: github.repository == '' name: "Local: Build and unit testing on Windows" runs-on: [self-hosted, Windows, pymapdl] timeout-minutes: 30 @@ -473,6 +474,7 @@ jobs: steps: - uses: actions/checkout@v3 + # Skipping because it is installed locally. # - name: Setup Python # uses: actions/setup-python@v4.3.2 # with: @@ -508,15 +510,15 @@ jobs: # docker pull ghcr.io/pyansys/dpf-core:22.2dev # docker run -d --name dpfserver -p ${{ env.DPF_PORT }}:50052 ghcr.io/pyansys/dpf-core:22.2dev && echo "DPF Server active on port ${{ env.DPF_PORT }}." - # - name: "Unit testing" - # shell: powershell - # run: | - # set PYMAPDL_PORT= - # set PYMAPDL_START_INSTANCE= - # python -m pytest -v -k "not test_database and not test_dpf" --durations=10 --maxfail=10 --reruns 7 --reruns-delay 3 --only-rerun MapdlExitedError --only-rerun EmptyRecordError --cov=ansys.mapdl.core --cov-report=xml --cov-report=html + - name: "Unit testing" + shell: powershell + run: | + set PYMAPDL_PORT= + set PYMAPDL_START_INSTANCE= + python -m pytest -v -k "not test_database and not test_dpf" --durations=10 --maxfail=10 --reruns 7 --reruns-delay 3 --only-rerun MapdlExitedError --only-rerun EmptyRecordError --cov=ansys.mapdl.core --cov-report=xml --cov-report=html - # - uses: codecov/codecov-action@v3 - # name: "Upload coverage to Codecov" + - uses: codecov/codecov-action@v3 + name: "Upload coverage to Codecov" release: if: github.event_name == 'push' && contains(github.ref, 'refs/tags') From a29532ecbd6844112346be7f35f22058a51e7df6 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 14 Dec 2022 21:40:27 +0100 Subject: [PATCH 11/16] Update doc/source/user_guide/troubleshoot.rst --- doc/source/user_guide/troubleshoot.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index e7cebb8c67..f036777382 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -591,7 +591,7 @@ issue is already listed. If not, you can do one of the following: * Go to the `PyMAPDL Discussions `_ page and create a discussion about your issue. -* Go to the `PyMAPDL Issues `_ if you have found a bug - or want to create a feature request. +* Go to the `PyMAPDL Issues `_ if you have found a bug + or want to create a feature request. . From 21fa5d165b1228e8bc3e299d24c7e62ff3603ef0 Mon Sep 17 00:00:00 2001 From: German Date: Wed, 14 Dec 2022 22:02:56 +0100 Subject: [PATCH 12/16] line --- doc/source/user_guide/troubleshoot.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index f036777382..21d8780cb3 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -593,5 +593,4 @@ issue is already listed. If not, you can do one of the following: * Go to the `PyMAPDL Issues `_ if you have found a bug or want to create a feature request. - . From aa30e6f162deb02cba919a6ecbe08a7dfcdc6c68 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 15 Dec 2022 10:14:17 +0100 Subject: [PATCH 13/16] Apply suggestions from code review --- doc/source/getting_started/docker.rst | 2 +- doc/source/user_guide/troubleshoot.rst | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index 29032dcbde..ec0e65fdb6 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -86,7 +86,7 @@ There are several images in the registry, each corresponding to a different version of MAPDL. For Ubuntu systems (any image tagged as ``Ubuntu``), you should use the latest version of MAPDL. -To rerun it again, you should restart the container or just delete it and run it again using: +To rerun it, you should restart the container or just delete it and run it again using: .. code:: pwsh diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 21d8780cb3..1e0a9b8530 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -588,9 +588,11 @@ More help needed? Go to the `PyMAPDL Issues `_ page and search to see if your issue is already listed. If not, you can do one of the following: -* Go to the `PyMAPDL Discussions `_ page and - create a discussion about your issue. +* Go to the `PyMAPDL Discussions `_ page and + create a discussion about your issue. * Go to the `PyMAPDL Issues `_ if you have found a bug - or want to create a feature request. + or want to create a feature request. + +For more complex issues or queries please contact `PyAnsys Support `_. From c1ea9057e6c648dc34f0a64a0e26d52ba7f7a7ea Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 15 Dec 2022 16:13:44 +0100 Subject: [PATCH 14/16] Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/user_guide/troubleshoot.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 1e0a9b8530..0052367c3d 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -409,7 +409,7 @@ as the first parameter to :func:`launch_mapdl() ` -Default Location of the executable file +Default location of the executable file --------------------------------------- The first time that you run PyMAPDL, it detects the @@ -557,13 +557,16 @@ When connecting to an instance of MAPDL using gRPC (default), there are some cas where the MAPDL server might exit unexpectedly. There are several ways to improve MADPL performance and 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 - your program or script so that you can turn on and off logging and - verbosity as needed. +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 +your program or script so that you can turn on and off logging and +verbosity as needed. Issues @@ -589,10 +592,9 @@ Go to the `PyMAPDL Issues `_ page and search to see if your issue is already listed. If not, you can do one of the following: * Go to the `PyMAPDL Discussions `_ page and - create a discussion about your issue. - + create a discussion about your issue. * Go to the `PyMAPDL Issues `_ if you have found a bug - or want to create a feature request. + or want to create a feature request. -For more complex issues or queries please contact `PyAnsys Support `_. +For more complex issues or queries, contact `PyAnsys Support `_. From 8d056c0c4b296cfbfafe77b507de33fa246d5d9d Mon Sep 17 00:00:00 2001 From: German Date: Thu, 15 Dec 2022 16:38:50 +0100 Subject: [PATCH 15/16] removing the graphviz --- doc/source/getting_started/docker.rst | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index ec0e65fdb6..b379c49bb1 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -55,22 +55,6 @@ directly from the command line. You can then use your host Python environment to connect to that MAPDL instance. -.. graphviz:: - - digraph { - node []; - subgraph cluster_frontend { - label="*HOST*"; - Python; - subgraph cluster_backend { - MAPDL; - label="*DOCKER*"; - } - } - Python -> MAPDL - MAPDL -> Python - } - Because this image does not contain a license server, you must enter your license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable. From 29d24e93a3f712906c431ca73591142e95ba8f73 Mon Sep 17 00:00:00 2001 From: German Date: Thu, 15 Dec 2022 17:16:29 +0100 Subject: [PATCH 16/16] fixing pdf building --- doc/Makefile | 2 +- doc/source/getting_started/docker.rst | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/doc/Makefile b/doc/Makefile index 7a16336dd0..a2d5a0f096 100755 --- a/doc/Makefile +++ b/doc/Makefile @@ -38,7 +38,7 @@ pdf: @$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) python validate_png.py # clean-up GIFs mislabeled as PNG cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true - (test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1 + (test -f $(BUILDDIR)/latex/pymapdl-Documentation-*.pdf && echo pdf exists) || exit 1 checklinks: $(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) $(LINKCHECKDIR) diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index b379c49bb1..ec0e65fdb6 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -55,6 +55,22 @@ directly from the command line. You can then use your host Python environment to connect to that MAPDL instance. +.. graphviz:: + + digraph { + node []; + subgraph cluster_frontend { + label="*HOST*"; + Python; + subgraph cluster_backend { + MAPDL; + label="*DOCKER*"; + } + } + Python -> MAPDL + MAPDL -> Python + } + Because this image does not contain a license server, you must enter your license server IP address in the ``ANSYSLMD_LICENSE_FILE`` environment variable.