From cbadf1886403d01fc1a0bc3b0861e75a7e1deb98 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 11:33:18 +0100 Subject: [PATCH 1/5] Improve launcher documentation (#2488) * * Reorg of getting started. * Update versions * Small fixes * Fixing vale * Shortening line * Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> * typo * typos * first windows commands, later linux. Making those bold titled. --------- Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/getting_started/contribution.rst | 4 +- doc/source/getting_started/docker.rst | 23 +- doc/source/getting_started/faq.rst | 27 +- doc/source/getting_started/index.rst | 116 +-------- doc/source/getting_started/install_mapdl.rst | 56 +++++ .../getting_started/install_pymapdl.rst | 84 +++++++ doc/source/getting_started/launcher.rst | 235 ++++++++++++++++++ doc/source/getting_started/running_mapdl.rst | 145 ----------- doc/source/getting_started/using_julia.rst | 4 +- doc/source/index.rst | 7 +- doc/source/links.rst | 2 +- doc/source/user_guide/index.rst | 35 ++- doc/source/user_guide/launcher.rst | 84 ------- doc/source/user_guide/mapdl.rst | 2 +- doc/source/user_guide/troubleshoot.rst | 60 +++-- examples/00-mapdl-examples/lathe_cutter.py | 4 +- src/ansys/mapdl/core/misc.py | 8 +- src/ansys/mapdl/core/pool.py | 10 +- 18 files changed, 486 insertions(+), 420 deletions(-) create mode 100644 doc/source/getting_started/install_mapdl.rst create mode 100644 doc/source/getting_started/install_pymapdl.rst create mode 100644 doc/source/getting_started/launcher.rst delete mode 100644 doc/source/getting_started/running_mapdl.rst delete mode 100644 doc/source/user_guide/launcher.rst diff --git a/doc/source/getting_started/contribution.rst b/doc/source/getting_started/contribution.rst index 5be0ac5c19..8c2662d325 100644 --- a/doc/source/getting_started/contribution.rst +++ b/doc/source/getting_started/contribution.rst @@ -58,7 +58,7 @@ 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. -In Windows, use: +**On Windows** .. code:: pwsh-session @@ -66,7 +66,7 @@ In Windows, use: SET PYMAPDL_PORT= (default 50052) SET PYMAPDL_IP= (default 127.0.0.1) -In Linux, use: +**On Linux** .. code:: console diff --git a/doc/source/getting_started/docker.rst b/doc/source/getting_started/docker.rst index c1a6ff5b54..e892b3268f 100644 --- a/doc/source/getting_started/docker.rst +++ b/doc/source/getting_started/docker.rst @@ -85,15 +85,6 @@ container. To instantiate an MAPDL Docker container from an image hosted at ``ghcr.io/myuser/myrepo/mymapdldockerimage``, use code like in the following examples. -**On Linux** - -.. code:: bash - - ANSYSLMD_LICENSE_FILE=1055@MY_LICENSE_SERVER_IP - LOCAL_MAPDL_PORT=50053 - MAPDL_DOCKER_REGISTRY_URL=ghcr.io/myuser/myrepo/mymapdldockerimage - docker run -e ANSYSLMD_LICENSE_FILE=$ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $LOCAL_MAPDL_PORT:50052 $MAPDL_DOCKER_REGISTRY_URL -smp > log.txt - **On Windows** .. code:: pwsh-session @@ -105,6 +96,16 @@ use code like in the following examples. docker run -e ANSYSLMD_LICENSE_FILE=$env:ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $env:LOCAL_MAPDL_PORT`:50052 $env:MAPDL_DOCKER_REGISTRY_URL -smp +**On Linux** + +.. code:: bash + + ANSYSLMD_LICENSE_FILE=1055@MY_LICENSE_SERVER_IP + LOCAL_MAPDL_PORT=50053 + MAPDL_DOCKER_REGISTRY_URL=ghcr.io/myuser/myrepo/mymapdldockerimage + docker run -e ANSYSLMD_LICENSE_FILE=$ANSYSLMD_LICENSE_FILE --restart always --name mapdl -p $LOCAL_MAPDL_PORT:50052 $MAPDL_DOCKER_REGISTRY_URL -smp > log.txt + + The first time you instantiate the container, Docker logins into the registry and pulls the required image. This can take some time, depending on the size of the image. @@ -162,10 +163,10 @@ number available on the host machine) with the ``-np`` switch: For additional command line arguments, see the *Notes* section in the -description for the :func:`launch_mapdl() ` +description for the :func:`launch_mapdl() ` function. -You can use a script file (batch ``'.bat'`` or PowerShell ``'.ps'``) +You can 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 the following content diff --git a/doc/source/getting_started/faq.rst b/doc/source/getting_started/faq.rst index 818e09e33e..f18f980150 100644 --- a/doc/source/getting_started/faq.rst +++ b/doc/source/getting_started/faq.rst @@ -7,11 +7,15 @@ Frequently asked questions How do you report issues? ========================= -To report bugs and documentation errors and to make feature requests, use the `PyMAPDL issues `_ page of -the GitHub repository. +If you find an issue, the first place to visit for possible solutions is the :ref:`troubleshooting section `. -To ask more open-ended questions or seek advice from the community, use the `PyMAPDL discussions `_ page -of the GitHub repository. +If you do not find a solution there, you can search for your issue within the `GitHub repository `_. You can use `the search box `_ to find related issues or pull requests. + +To ask more open-ended questions or seek advice from the community, +use the `PyMAPDL discussions `_ page of the GitHub repository. + +To report bugs and documentation errors and to make feature requests, +use the `PyMAPDL issues `_ page of the GitHub repository. What are the pros and cons of PyMAPDL versus Ansys ACT? @@ -44,12 +48,15 @@ like to develop software. Has APDL been "deprecated" by Ansys? If so, what does that mean for PyMAPDL? ============================================================================ -APDL isn't going anywhere. In fact, whenever you call Mechanical Workbench, it's generating an input file -(``ds.dat``) that's fed into MAPDL. However, what's changed over the past several years is where the geometry, -meshing, and postprocessing is occurring. Geometry generation can take place within SpaceClaim or Design Modeler, -and meshing is done using a variety of new and powerful meshers within Workbench. While these tools are -far superior to the ones in MAPDL, their biggest limitation is that they're difficult to script -(especially externally). As a result, there are still users who choose to generate the geometry and mesh within MAPDL. +APDL isn't going anywhere. In fact, whenever you call Mechanical Workbench, it's +generating an input file (``ds.dat``) that's fed into MAPDL. However, what's +changed over the past several years is where the geometry, meshing, and +postprocessing is occurring. Geometry generation can take place within +SpaceClaim or Design Modeler, and meshing is done using a variety of new and +powerful meshers within Workbench. While these tools are far superior to the +ones in MAPDL, their biggest limitation is that they're difficult to script +(especially externally). As a result, there are still users who choose to +generate the geometry and mesh within MAPDL. What are the main reasons to use PyMAPDL over other Ansys products like Workbench? diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 75d5f6cfda..5936e3dbd9 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -1,122 +1,30 @@ -=============== -Getting started -=============== -To use PyMAPDL, you must have a local installation of Ansys. The -version of Ansys installed dictates the interface and features -available to you. - -For more information on getting a licensed copy of Ansys, visit -`Ansys `_. .. toctree:: :hidden: :maxdepth: 3 + install_mapdl + install_pymapdl + launcher learning + contribution + faq versioning - running_mapdl docker macos wsl using_julia - faq - contribution make_container_link devcontainer_link -.. _installation: - -************ -Installation -************ - -Python module -~~~~~~~~~~~~~ -The ``ansys.mapdl.core`` package currently supports Python 3.8 through -Python 3.12 on Windows, Mac OS, and Linux. - -Install the latest release from -`PyPi `_ with: - -.. code:: console - - pip install ansys-mapdl-core - -Alternatively, install the latest from -`PyMAPDL GitHub `_ via: - -.. code:: console - - pip install git+https://github.com/ansys/pymapdl.git - - -For a local *development* version, install with: - -.. code:: console - - git clone https://github.com/ansys/pymapdl.git - cd pymapdl - pip install -e . - -This allows you to install the ``ansys-mapdl-core`` module -and modify it locally and have the changes reflected in your setup -after restarting the Python kernel. - - -Offline installation -~~~~~~~~~~~~~~~~~~~~ -If you lack an internet connection on your install machine, the recommended way -of installing PyMAPDL is downloading the wheelhouse archive from the -`Releases Page `_ for your corresponding -machine architecture. - -Each wheelhouse archive contains all the Python wheels necessary to install -PyMAPDL from scratch on Windows and Linux for Python 3.8 and 3.9. You can install -this on an isolated system with a fresh Python or on a virtual environment. - -For example, on Linux with Python 3.8, unzip it and install it with the following: - -.. code:: console - - unzip PyMAPDL-v0.62.dev1-wheelhouse-Linux-3.8.zip wheelhouse - pip install ansys-mapdl-core -f wheelhouse --no-index --upgrade --ignore-installed - -If you're on Windows with Python 3.9, unzip to a ``wheelhouse`` directory and -install using the preceding command. - -Consider installing using a `virtual environment `_. - - -Ansys software requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For the latest features, you must have a copy of Ansys 2021 R1 -installed locally. However, PyMAPDL is compatible with Ansys 17.0 and later -on Windows and with Ansys 13.0 on Linux. - -.. note:: - - The latest versions of Ansys provide significantly better support - and features. Certain features are not supported on earlier - Ansys versions. - -For more information, see :ref:`install_mapdl`. - -Verify your installation -~~~~~~~~~~~~~~~~~~~~~~~~ -Check that you can start MAPDL from Python by running: - -.. code:: pycon - - >>> from ansys.mapdl.core import launch_mapdl - >>> mapdl = launch_mapdl() - >>> print(mapdl) +=============== +Getting started +=============== - Product: ANSYS Mechanical Enterprise - MAPDL Version: RELEASE 2021 R1 BUILD 21.0 - PyMAPDL Version: Version: 0.58.0 +To use PyMAPDL you must follow the next three steps: -If you see a response from the server, congratulations. You're ready -to get started using MAPDL as a service. For information on the -PyMAPDL interface, see :ref:`ref_mapdl_user_guide`. +* :ref:`ref_using_standard_install` +* :ref:`ref_pymapdl_installation` +* :ref:`ref_launch_pymapdl` diff --git a/doc/source/getting_started/install_mapdl.rst b/doc/source/getting_started/install_mapdl.rst new file mode 100644 index 0000000000..49a0d56579 --- /dev/null +++ b/doc/source/getting_started/install_mapdl.rst @@ -0,0 +1,56 @@ + + +.. _ref_using_standard_install: install_mapdl_ + +.. _install_mapdl: + +************* +Install MAPDL +************* + + +The PyAnsys ``ansys-mapdl-core`` package (PyMAPDL) requires either a local or +remote instance of MAPDL to communicate with it. This section covers +launching and interfacing with MAPDL from a local instance by +launching it from Python. + +MAPDL is installed by default from the Ansys standard installer. When +installing Ansys, verify that the **Mechanical Products** checkbox is +selected under the **Structural Mechanics** option. While the standard +installer options can change, see the following figure for reference. + +.. figure:: ../images/unified_install_2019R1.jpg + :width: 400pt + + +If you want to avoid having to install MAPDL locally, you can use Docker. +This is especially convenient if you are using a non-supported platform such +as MacOS. +For more information, see :ref:`ref_pymapdl_and_macos`. + +You can also download and try the `Ansys Student Version `_. +A Student Version is valid during a calendar year with limited capabilities. For +example, there is a limit on the number of nodes and elements. + +If you experience problems installing MAPDL on Linux, see +:ref:`missing_dependencies_on_linux`. + + +Ansys software requirements +--------------------------- + +For the latest features, you must have a copy of Ansys 2021 R1 or later +installed locally. However, PyMAPDL is compatible with Ansys 17.0 and later +on Windows and with Ansys 13.0 on Linux. However, its usage with these older +versions is discouraged. + +.. note:: + + The latest versions of Ansys provide significantly better support + and features. Certain features are not supported on earlier + Ansys versions. + +For more information, see :ref:`versions_and_interfaces`. + + +For information on installing PyMAPDL, see :ref:`ref_pymapdl_installation`. \ No newline at end of file diff --git a/doc/source/getting_started/install_pymapdl.rst b/doc/source/getting_started/install_pymapdl.rst new file mode 100644 index 0000000000..d0b6034e55 --- /dev/null +++ b/doc/source/getting_started/install_pymapdl.rst @@ -0,0 +1,84 @@ + + +.. _ref_pymapdl_installation: + +*************** +Install PyMAPDL +*************** + +Python module +~~~~~~~~~~~~~ +The ``ansys.mapdl.core`` package currently supports Python 3.8 through +Python 3.11 on Windows, Mac OS, and Linux. + +Install the latest release from `PyPi `_ with: + +.. code:: console + + pip install ansys-mapdl-core + +Alternatively, install the latest from +`PyMAPDL GitHub `_ with this command: + +.. code:: console + + pip install git+https://github.com/ansys/pymapdl.git + + +For a local *development* version, install with these commands: + +.. code:: console + + git clone https://github.com/ansys/pymapdl.git + cd pymapdl + pip install -e . + +After installing a development version, you can modify the ``ansys-mapdl-core`` package +locally and have the changes reflected in your setup after restarting the Python kernel. + + +Offline installation +~~~~~~~~~~~~~~~~~~~~ +If you lack an internet connection on your installation machine, the recommended way +of installing PyMAPDL is downloading the wheelhouse archive from the +`Releases `_ page for your corresponding +machine architecture. + +Each wheelhouse archive contains all the Python wheels necessary to install +PyMAPDL from scratch on Windows and Linux. You can install +this on an isolated system with a fresh Python installation or on a virtual environment. + +For example, on Linux with Python 3.9, unzip the wheelhouse archive and install it with +these commands: + +.. code:: console + + unzip PyMAPDL-v0.68.dev1-wheelhouse-Linux-3.9.zip wheelhouse + pip install ansys-mapdl-core -f wheelhouse --no-index --upgrade --ignore-installed + +If you're on Windows with Python 3.9, unzip to a ``wheelhouse`` directory and +install using the preceding command. + +Consider installing using a `virtual environment `_. + +Verify your installation +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + To use PyMAPDL, you must have a local installation of Ansys. The + version of Ansys installed dictates the interface and features + available to you. + + For more information on getting a licensed copy of Ansys, visit + `Ansys `_. + + +Check that you have installed the package correctly by importing the module: + +.. code:: pycon + + >>> from ansys.mapdl import core as pymapdl + + +For information on launching PyMAPDL and connecting it +to an MAPDL instance, see:ref:`ref_launch_pymapdl`. diff --git a/doc/source/getting_started/launcher.rst b/doc/source/getting_started/launcher.rst new file mode 100644 index 0000000000..df173b2433 --- /dev/null +++ b/doc/source/getting_started/launcher.rst @@ -0,0 +1,235 @@ + + +.. _ref_launch_pymapdl: + + +Launch PyMAPDL +============== + +PyMAPDL can start MAPDL locally, or it can connect to a session already running locally or +on a remote machine. + +* `Launch PyMAPDL with a local MAPDL instance`_ +* `Connect PyMAPDL to a local MAPDL instance`_ +* `Connect PyMAPDL to a remote MAPDL instance`_ + +If you have any problem launching PyMAPDL, see :ref:`Launching issues `. + + +Launch PyMAPDL with a local MAPDL instance +------------------------------------------ + +You can use the :func:`launch_mapdl() ` +function to start MAPDL and automatically connect to it: + +.. code:: pycon + + >>> from ansys.mapdl.core import launch_mapdl + >>> mapdl = launch_mapdl() + >>> print(mapdl) + Product: Ansys Mechanical Enterprise + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.0 + + +While this is the easiest and fastest way to get PyMAPDL up and running. +you must be able to launch MAPDL locally. + +If PyMAPDL cannot find your local installation, see +`Setting the MAPDL location in PyMAPDL`_. + +For more information on controlling how MAPDL launches locally, see the +description of the :func:`launch_mapdl() ` function. + + +Connect PyMAPDL to a local MAPDL instance +----------------------------------------- + +Connect to a local MAPDL instance requires two steps: launching a +local MAPDL session and connect to it. + +.. _launch_grpc_madpl_session: + +Launch a local gRPC MAPDL session +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can start MAPDL from the command line and then connect to it. + +To launch MAPDL on Windows (assuming that Ansys is installed in the +:file:`C:/Program Files/ANSYS Inc/v241` directory), use this command: + +.. code:: pwsh-session + + C:/Program Files/ANSYS Inc/v241/ansys/bin/winx64/ANSYS211.exe -grpc + +To launch MAPDL on Linux (assuming that Ansys is installed in the +:file:`/usr/ansys_inc` directory), use this command: + +.. code:: console + + /usr/ansys_inc/v241/ansys/bin/ansys211 -grpc + +This starts MAPDL in gRPC mode. MAPDL should display this output: + +.. code:: output + + Start GRPC Server + + ############################## + ### START GRPC SERVER ### + ############################## + + Server Executable : MapdlGrpc Server + Server listening on : 0.0.0.0:50052 + +You can configure the port that MAPDL starts on with the ``-port`` argument. +For example, you can start the server to listen for connections at +port 50005 with this command: + +.. code:: console + + /usr/ansys_inc/v241/ansys/bin/ansys211 -port 50005 -grpc + + +.. _connect_grpc_madpl_session: + +Connect to the local MAPDL instance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An MAPDL gRPC server can be connected to from the same host by using +this code: + +.. code:: pycon + + >>> from ansys.mapdl.core import Mapdl + >>> mapdl = Mapdl() + +The preceding code assumes that your MAPDL service is running locally on the default IP address +(``127.0.0.1``) and on the default port (``50052``). + +You can also use the :func:`launch_mapdl() ` method to connect to an already launched MAPDL instance by setting the ``start_instance`` argument to ``False``: + +.. code:: pycon + + >>> from ansys.mapdl.core import launch_mapdl + >>> mapdl = launch_mapdl(start_instance=False) + +If you are connecting to an MAPDL Docker image, the procedure is the same. +Just make sure that you specify the mapped port instead of the internal MAPDL port. +For more information, see :ref:`pymapdl_docker`. + + +.. _connect_grpc_remote_madpl_session: + +Connect PyMAPDL to a remote MAPDL instance +------------------------------------------ + +If you want to connect to a **remote** MAPDL instance, you must know the IP +address of that instance. +For example, if on your local network at IP address ``192.168.0.1`` there is a +computer running MAPDL on the port ``50052``, you can connect to it with this code: + +.. code:: pycon + + >>> mapdl = Mapdl("192.168.0.1", port=50052) + +Alternatively, you can use a hostname: + +.. code:: pycon + + >>> mapdl = Mapdl("myremotemachine", port=50052) + +Note that you must have started an MAPDL instance in gRPC mode on the computer with +the referenced IP address and hostname for this to work because PyMAPDL cannot launch remote instances. + + +Setting the MAPDL location in PyMAPDL +------------------------------------- + +To run, PyMAPDL must know the location of the MAPDL binary. +Most of the time this can be automatically determined, but +the location of MAPDL must be provided for non-standard installations. +When running for the first time, PyMAPDL requests the +location of the MAPDL executable if it cannot automatically find it. + +You can test your installation of PyMAPDL and set it up by running +the :func:`launch_mapdl() ` function: + +.. code:: python + + from ansys.mapdl.core import launch_mapdl + + mapdl = launch_mapdl() + +Python automatically attempts to detect your MAPDL binary based on +environmental variables. +You can specify an MAPDL installation using one of two environment +variables: + +* ``AWP_ROOTXXX``, where ``XXX``` is the three-digit version. This environment variable + contains the path of the Ansys installation with the version matching ``XXX``. + For example, ``AWP_ROOT222=/ansys_inc`` contains the path to an Ansys 2022 R2 installation. + +* ``PYMAPDL_MAPDL_EXEC`` contains the path to the Ansys MAPDL executable file. + For example, ``PYMAPDL_MAPDL_EXEC=/ansys_inc/v222/ansys/bin/ansys222``. + +If PyMAPDL is unable to find a copy of MAPDL, you +are prompted for the location of the MAPDL executable. + +Here is the prompt with an example response for Windows: + +.. code:: output + + Enter location of MAPDL executable: C:\Program Files\ANSYS Inc\v222\ANSYS\bin\winx64\ansys222.exe + +Here is the prompt with an example response for Linux: + +.. code:: output + + Enter location of MAPDL executable: /usr/ansys_inc/v222/ansys/bin/ansys222 + +The settings file is stored locally, which means that you are not prompted +to enter the path again. If you must change the default Ansys path +(meaning change the default version of MAPDL), run this code: + +.. code:: python + + from ansys.mapdl import core as pymapdl + + new_path = "C:\\Program Files\\ANSYS Inc\\v212\\ANSYS\\bin\\winx64\\ansys222.exe" + pymapdl.change_default_ansys_path(new_path) + +For more information, see the :func:`change_default_ansys_path() ` method and the :func:`find_ansys() ` method. + +Additionally, it is possible to specify the executable in each PyMAPDL script using the ``exec_file`` keyword argument. + + +**On Windows:** + +.. code:: python + + from ansys.mapdl.core import launch_mapdl + + mapdl = launch_mapdl( + exec_file="C://Program Files//ANSYS Inc//v212//ANSYS//bin//winx64//ansys212.exe" + ) + +**On Linux:** + +.. code:: python + + from ansys.mapdl.core import launch_mapdl + + mapdl = launch_mapdl(exec_file="/usr/ansys_inc/v212/ansys/bin/ansys212") + + +You could also specify a custom executable made from a custom MAPDL compilation by adding the correspondent flag (``-custom``) to the ``additional_switches`` +keyword argument: + +.. code:: python + + from ansys.mapdl.core import launch_mapdl + + custom_exec = "/usr/ansys_inc/v212/ansys/bin/ansys212t" + add_switch = f" -custom {custom_exec}" + mapdl = launch_mapdl(additional_switches=add_switch) diff --git a/doc/source/getting_started/running_mapdl.rst b/doc/source/getting_started/running_mapdl.rst deleted file mode 100644 index 2603c73f2d..0000000000 --- a/doc/source/getting_started/running_mapdl.rst +++ /dev/null @@ -1,145 +0,0 @@ -.. _using_standard_install: - -********************* -Standard installation -********************* - -The PyAnsys ``ansys-mapdl-core`` package requires either a local or -remote instance of MAPDL to communicate with it. This section covers -launching and interfacing with MAPDL from a local instance by -launching it from Python. - - -.. _install_mapdl: - -Install MAPDL -------------- - -MAPDL is installed by default from the Ansys standard installer. When -installing Ansys, verify that the **Mechanical Products** checkbox is -selected under the **Structural Mechanics** option. While the standard -installer options can change, see the following figure for reference. - -.. figure:: ../images/unified_install_2019R1.jpg - :width: 400pt - - -If you want to avoid having to install MAPDL locally, you can use Docker. -This is especially convenient if you are using a non-supported platform such -as MacOS. -For more information, see :ref:`ref_pymapdl_and_macos`. - -You can also download and try the `Ansys Student Versions `_. -A Student Version is valid during a calendar year with limited capabilities. For -example, there is a limit on the number of nodes and elements. - -If you experience problems installing MAPDL on Linux, see -:ref:`missing_dependencies_on_linux`. - -Launch MAPDL ------------- - -Launch MAPDL locally -~~~~~~~~~~~~~~~~~~~~ - -You can use the :func:`launch_mapdl() ` method to have Python start MAPDL and -automatically connect to it: - -.. code:: pycon - - >>> from ansys.mapdl.core import launch_mapdl - >>> mapdl = launch_mapdl() - >>> print(mapdl) - - Product: ANSYS Mechanical Enterprise - MAPDL Version: RELEASE 2021 R1 BUILD 21.0 - PyMAPDL Version: Version: 0.57.0 - - -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. - -To launch MAPDL on Windows (assuming a :file:`C:/Program Files/ANSYS Inc/v211` installation), use: - -.. code:: pwsh-session - - C:/Program Files/ANSYS Inc/v211/ansys/bin/winx64/ANSYS211.exe -grpc - -To launch MAPDL on Linux (assuming a :file:`/usr/ansys_inc` installation), use: - -.. code:: console - - /usr/ansys_inc/v211/ansys/bin/ansys211 -grpc - -This starts up MAPDL in gRPC mode, and MAPDL should output: - -.. code:: output - - Start GRPC Server - - ############################## - ### START GRPC SERVER ### - ############################## - - Server Executable : MapdlGrpc Server - Server listening on : 0.0.0.0:50052 - -You can configure the port that MAPDL starts on with the ``-port`` argument. -For example, you can start the server to listen for connections at -port 50005 with: - -.. code:: console - - /usr/ansys_inc/v211/ansys/bin/ansys211 -port 50005 -grpc - - -.. _connect_grpc_madpl_session: - -Connect to a gRPC MAPDL session -------------------------------- - -A MAPDL gRPC server can be connected to from either the same host or an -external host. For example, you can connect to a MAPDL service -running **locally** with: - -.. code:: pycon - - >>> from ansys.mapdl.core import Mapdl - >>> mapdl = Mapdl() - - -This assumes that your MAPDL service is running locally on the default IP address -(``127.0.0.1``) and on the default port (``50052``). - -If you want to connect to a **remote** instance of MAPDL and you know the IP -address of that instance, you can connect to it. -For example, if on your local network at IP address ``192.168.0.1`` there is a -computer running MAPDL on the port 50052, you can connect to it with: - -.. code:: pycon - - >>> mapdl = Mapdl("192.168.0.1", port=50052) - -Alternatively you can use a hostname: - -.. code:: pycon - - >>> mapdl = Mapdl("myremotemachine", port=50052) - -Note that you must have started MAPDL in gRPC mode on the computer with -the mentioned IP address/hostname for this to work. - -If you have MAPDL installed on your local host, you -can use the :func:`launch_mapdl() ` method to both start and connect to MAPDL. - -If you have any problem launching PyMAPDL, see :ref:`Launching issues `. - -If you are connecting to an MAPDL Docker image, the procedure is the same. -Just make sure that you specify the mapped port instead of the internal Docker image port. -For more information, see :ref:`pymapdl_docker`. diff --git a/doc/source/getting_started/using_julia.rst b/doc/source/getting_started/using_julia.rst index 659cef73c5..bdb8c7bffd 100644 --- a/doc/source/getting_started/using_julia.rst +++ b/doc/source/getting_started/using_julia.rst @@ -122,8 +122,8 @@ Finally, after restarting Julia, you can import PyMAPDL using the same procedure julia> mapdl = pymapdl.launch_mapdl() julia> print(mapdl.__str__()) Product: Ansys Mechanical Enterprise - MAPDL Version: 21.2 - ansys.mapdl Version: 0.60.6 + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.0 .. note:: If you experience errors when using PyCall, you can try to rebuild the package by pressing ``"]"`` to go to the package manager and typing: diff --git a/doc/source/index.rst b/doc/source/index.rst index fe5c6ff1c9..9cf5c570ec 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -74,10 +74,9 @@ Here's a brief example of how PyMAPDL works: >>> from ansys.mapdl.core import launch_mapdl >>> mapdl = launch_mapdl() >>> print(mapdl) - - Product: ANSYS Mechanical Enterprise - MAPDL Version: RELEASE 2021 R1 BUILD 21.0 - PyMAPDL Version: Version: 0.57.0 + Product: Ansys Mechanical Enterprise + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.0 MAPDL is now active and you can send commands to it as a genuine Python class. For example, if you wanted to create a surface using diff --git a/doc/source/links.rst b/doc/source/links.rst index a4a445b702..b1fb34392a 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -148,10 +148,10 @@ .. _pymapdl_discussion_differences_mapdl_pymapdl: https://github.com/ansys/pymapdl-reader/issues/185 .. _cartpole_example_notebook: https://cartpole.mapdl.docs.pyansys.com/ml-rl-notebook.html .. _wsl_launching_mapdl: https://github.com/ansys/pymapdl/issues/2315 +.. _pymapdl_search_issues_pr: https://github.com/ansys/pymapdl/issues?q= .. _pymapdl_latest_github_release: https://github.com/ansys/pymapdl/releases/latest .. _pymapdl_latest_pdf_doc: https://github.com/ansys/pymapdl/releases/download/v%%PYMAPDLVERSION%%.0/pymapdl-Documentation-%%PYMAPDLVERSION%%.0.pdf - .. #Python .. _using_venv: https://docs.python.org/3/library/venv.html .. _conda: https://conda.io diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index ca2df903cb..9d4c4536da 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -14,16 +14,15 @@ This section provides a general overview of PyMAPDL and how you use it. :maxdepth: 1 :hidden: - launcher mapdl - mapdl_examples - plotting + convert mesh_geometry - post + plotting parameters components + post + mapdl_examples database - convert math pool xpl @@ -34,18 +33,18 @@ This section provides a general overview of PyMAPDL and how you use it. PyMAPDL overview ================ -The :func:`launch_mapdl() ` function +The :func:`launch_mapdl() ` function within the ``ansys-mapdl-core`` library creates an instance of the :class:`Mapdl ` class in the background and sends -commands to that service. Errors and warnings are processed +commands to that instance. Errors and warnings are processed Pythonically, letting you develop a script in real time, without worrying about it functioning correctly when deployed in batch mode. MAPDL can be started from Python in gRPC mode using the -:func:`launch_mapdl() ` method. This starts +:func:`launch_mapdl() ` method. This starts MAPDL in a temporary directory by default. You can change this to -your current directory with: +your current directory with this code: .. code:: python @@ -55,7 +54,7 @@ your current directory with: path = os.getcwd() mapdl = launch_mapdl(run_location=path) -MAPDL is now active, and you can send commands to it as a genuine a +MAPDL is now active, and you can send commands to it as a genuine Python class. For example, if you wanted to create a surface using key points, you could run: @@ -132,16 +131,16 @@ Additionally, exceptions are caught and handled within Python. >>> mapdl.run("AL, 1, 2, 3") - xception: - L, 1, 2, 3 + Exception: + AL, 1, 2, 3 - EFINE AREA BY LIST OF LINES - INE LIST = 1 2 3 - TRAVERSED IN SAME DIRECTION AS LINE 1) + DEFINE AREA BY LIST OF LINES + LINE LIST = 1 2 3 + (TRAVERSED IN SAME DIRECTION AS LINE 1) - ** ERROR *** CP = 0.338 TIME= 09:45:36 - eypoint 1 is referenced by only one line. Improperly connected line - et for AL command. + *** ERROR *** CP = 0.338 TIME= 09:45:36 + Keypoint 1 is referenced by only one line. Improperly connected line + set for AL command. For longer scripts, instead of sending commands to MAPDL as in the diff --git a/doc/source/user_guide/launcher.rst b/doc/source/user_guide/launcher.rst deleted file mode 100644 index cfc3c61941..0000000000 --- a/doc/source/user_guide/launcher.rst +++ /dev/null @@ -1,84 +0,0 @@ -Initial setup and launch of MAPDL locally ------------------------------------------ -To run, ``ansys.mapdl.core`` must know the location of the MAPDL -binary. Most of the time this can be automatically determined, but -the location of MAPDL must be provided for non-standard installations. -When running for the first time, ``ansys-mapdl-core`` requests the -location of the MAPDL executable if it cannot automatically find it. -You can test your installation of PyMAPDL and set it up by running -the :func:`launch_mapdl() ` function: - -.. code:: python - - from ansys.mapdl.core import launch_mapdl - - mapdl = launch_mapdl() - -Python automatically attempts to detect your MAPDL binary based on -environmental variables. If it is unable to find a copy of MAPDL, you -are prompted for the location of the MAPDL executable. - -Here is a sample input for Linux: - -.. code:: output - - Enter location of MAPDL executable: /usr/ansys_inc/v222/ansys/bin/ansys222 - -Here is a sample input for Windows: - -.. code:: output - - Enter location of MAPDL executable: C:\Program Files\ANSYS Inc\v222\ANSYS\bin\winx64\ansys222.exe - -The settings file is stored locally, which means that you are not prompted -to enter the path again. If you must change the default Ansys path -(meaning change the default version of MAPDL), run the following: - -.. code:: python - - from ansys.mapdl import core as pymapdl - - new_path = "C:\\Program Files\\ANSYS Inc\\v212\\ANSYS\\bin\\winx64\\ansys222.exe" - pymapdl.change_default_ansys_path(new_path) - -Also see the :func:`change_default_ansys_path() ` method and -the :func:`find_ansys() ` method. - -Additionally, it is possible to specify the executable using the keyword argument ``exec_file``. - -In Linux: - -.. code:: python - - from ansys.mapdl.core import launch_mapdl - - mapdl = launch_mapdl(exec_file="/usr/ansys_inc/v212/ansys/bin/ansys212") - - -In Windows: - -.. code:: python - - from ansys.mapdl.core import launch_mapdl - - mapdl = launch_mapdl( - exec_file="C://Program Files//ANSYS Inc//v212//ANSYS//bin//winx64//ansys212.exe" - ) - -You could also specify a custom executable by adding the correspondent flag (``-custom``) to the ``additional_switches`` -keyword argument: - -.. code:: python - - from ansys.mapdl.core import launch_mapdl - - custom_exec = "/usr/ansys_inc/v212/ansys/bin/ansys212t" - add_switch = f" -custom {custom_exec}" - mapdl = launch_mapdl(additional_switches=add_switch) - - - -API reference -~~~~~~~~~~~~~ -For more information on controlling how MAPDL launches locally, see the -description of the :func:`launch_mapdl() ` function. diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index bfaa5dc813..07e7fa7c73 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -896,7 +896,7 @@ These are described in the following table: +---------------------------------------+---------------------------------------------------------------------+ | :envvar:`PYMAPDL_START_INSTANCE` | Override the behavior of the | -| | :func:`ansys.mapdl.core.launch_mapdl` function | +| | :func:`ansys.mapdl.core.launcher.launch_mapdl` function | | | to only attempt to connect to existing | | | instances of PyMAPDL. Generally used | | | in combination with ``PYMAPDL_PORT``. | diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 13610d5bad..b007e0d9b0 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -55,21 +55,22 @@ There are several issues that can cause MAPDL not to launch, including: - `Using a proxy server`_ - `Firewall settings`_ +If you cannot find your issue, see `More help needed?`_. + Connection timeout ~~~~~~~~~~~~~~~~~~ In some networks, MAPDL might take longer than expected to connect to the license server or to the remote instance. -In those cases, you might see the following message: +In those cases, you might see this message: -.. vale off -.. rubric:: PyMAPDL is taking longer than expected to connect to an MAPDL session. Checking if there are any available licenses... +.. code:: output -.. vale on + PyMAPDL is taking longer than expected to connect to an MAPDL session. Checking if there are any available licenses... -You might consider to increase the starting timeout before trying other options. -The start timeout can be increased using: + +First try increasing the starting timeout using this code: .. code:: python @@ -380,7 +381,7 @@ When `gRPC `_ is used in a proxy environment, if a local address is speci as the connection destination, the gRPC implementation refers automatically to the proxy address. In this case, the local address cannot be referred, resulting in a connection error. As a workaround, you can set the environment variable ``NO_PROXY`` to your local address ``127.0.0.1``, -and then run :func:`launch_mapdl() ` +and then run :func:`launch_mapdl() ` to connect to MAPDL instance. @@ -420,7 +421,8 @@ Manually set the location of the executable file If you have a non-standard install, PyMAPDL might be unable find your MAPDL installation. If this is the case, provide the location of MAPDL -as the first parameter to :func:`launch_mapdl() `. +as the first parameter to the :func:`launch_mapdl() ` +method. **On Windows** @@ -454,7 +456,9 @@ Ansys installations are normally under: C:/Program Files/ANSYS Inc/vXXX + **On Linux** + Ansys installations are normally under: .. code:: text @@ -594,36 +598,38 @@ your program or script so that you can turn on and off logging and verbosity as needed. -Issues -~~~~~~ +Known 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. +* 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? ----------------- +.. vale off + .. epigraph:: - *"What do you do if a problem is not listed here?"* + *"What do I do if an issue is not listed here?"* + +.. vale on +To see if your issue is already posted, search the `PyMAPDL Issues `_ page. If not, do one of the following: -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: +* If you are not sure of the cause or would like some explanation about the + usage of the function or its documentation, create a discussion on the + `PyMAPDL Discussions `_ page. -* 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. +* If you believe you have found a bug or want to create a feature request, + create an issue on the `PyMAPDL Issues `_ page. -For more complex issues or queries, contact `PyAnsys Core team `_. +For more complex issues or queries, contact the `PyAnsys Core team `_. diff --git a/examples/00-mapdl-examples/lathe_cutter.py b/examples/00-mapdl-examples/lathe_cutter.py index d0c7cb1f3a..935e3139ac 100644 --- a/examples/00-mapdl-examples/lathe_cutter.py +++ b/examples/00-mapdl-examples/lathe_cutter.py @@ -81,7 +81,7 @@ ############################################################################### # Often used MAPDL command line options are exposed as Pythonic parameter names in -# :func:`ansys.mapdl.core.launch_mapdl`. For example, ``-dir`` +# :func:`ansys.mapdl.core.launcher.launch_mapdl`. For example, ``-dir`` # has become ``run_location``. # You could use ``run_location`` to specify the MAPDL run location. For example: # @@ -326,7 +326,7 @@ ############################################################################### # Get the principal nodal stresses of the node subset. -mapdl.nsel("S", "S", 1, 6700, 7720) +mapdl.nsel("S", vmin=1200, vmax=1210) mapdl.esln() mapdl.nsle() diff --git a/src/ansys/mapdl/core/misc.py b/src/ansys/mapdl/core/misc.py index c2fa1b0f2c..94268eca81 100644 --- a/src/ansys/mapdl/core/misc.py +++ b/src/ansys/mapdl/core/misc.py @@ -697,13 +697,13 @@ class Information: -------- >>> mapdl.info Product: Ansys Mechanical Enterprise - MAPDL Version: 21.2 - ansys.mapdl Version: 0.62.dev0 + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.0 >>> print(mapdl) Product: Ansys Mechanical Enterprise - MAPDL Version: 21.2 - ansys.mapdl Version: 0.62.dev0 + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.0 >>> mapdl.info.product 'Ansys Mechanical Enterprise' diff --git a/src/ansys/mapdl/core/pool.py b/src/ansys/mapdl/core/pool.py index 4a3b51f87c..e8eb9a3681 100755 --- a/src/ansys/mapdl/core/pool.py +++ b/src/ansys/mapdl/core/pool.py @@ -93,8 +93,8 @@ class LocalMapdlPool: By default, the instances directories are named as "Instances_{i}". **kwargs : dict, optional - See :func:`ansys.mapdl.core.launch_mapdl` for a complete - listing of all additional keyword arguments. + Additional keyword arguments. For a complete listing, see the description for the + :func:`ansys.mapdl.core.launcher.launch_mapdl` method. Examples -------- @@ -557,9 +557,9 @@ def next_available(self, return_index=False): -------- >>> mapdl = pool.next_available() >>> print(mapdl) - Product: ANSYS Mechanical Enterprise - MAPDL Version: RELEASE BUILD 0.0 UPDATE 0 - PyANSYS Version: 0.55.1 + Product: Ansys Mechanical Enterprise + MAPDL Version: 24.1 + ansys.mapdl Version: 0.68.dev0 """ # loop until the next instance is available From 757364a62148a50c56fca98d205d754c80f14a1a Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 12:00:04 +0100 Subject: [PATCH 2/5] Allowing latest as version (#2515) * Allowing latest as version * Adding test * version checking after PIM launcher --------- Co-authored-by: Camille <78221213+clatapie@users.noreply.github.com> --- src/ansys/mapdl/core/launcher.py | 9 ++++++--- tests/test_launcher.py | 4 ++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 9a23856417..ff1620e2ab 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1435,8 +1435,6 @@ def launch_mapdl( if version is None: version = os.getenv("PYMAPDL_MAPDL_VERSION", None) - version = _verify_version(version) # return a int version or none - # Start MAPDL with PyPIM if the environment is configured for it # and the user did not pass a directive on how to launch it. if _HAS_PIM and exec_file is None and pypim.is_configured(): @@ -1448,6 +1446,8 @@ def launch_mapdl( return launch_remote_mapdl(cleanup_on_exit=cleanup_on_exit, version=version) + version = _verify_version(version) # return a int version or none + # connect to an existing instance if enabled if start_instance is None: if "PYMAPDL_START_INSTANCE" in os.environ: @@ -1882,7 +1882,10 @@ def _verify_version(version): version = int(version * 10) if isinstance(version, str): - if version.upper().strip() in [ + if version.lower().strip() == "latest": + return None # Default behaviour is latest + + elif version.upper().strip() in [ str(each) for each in SUPPORTED_ANSYS_VERSIONS.keys() ]: version = int(version) diff --git a/tests/test_launcher.py b/tests/test_launcher.py index 13c414f683..11c055ca60 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -400,6 +400,10 @@ def test__verify_version_pass(version): assert min(versions.keys()) <= ver <= max(versions.keys()) +def test__verify_version_latest(): + assert _verify_version("latest") is None + + @requires("ansys-tools-path") @requires("local") def test_find_ansys(mapdl): From 94320a623b93f883a0fd2a1917882660cca1b06f Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 12:00:46 +0100 Subject: [PATCH 3/5] Moving functions to Mapdl class (#2468) * Moving parres and inquire * Moving lgwrite * Moving VWRITE * Moving *USE * Moving NRM * Moving /COM * Moving LSSOLVE * fixing typo * Disabling Google heading. Adding `mapdl` (lowercase) to accepts. Fixing other warnings. * fixing vale version to avoid pipeline unexpected breakdowns. * Undoing changes from main * Empty comment to trigger CICD * Empty commit to re-trigger CICD * Fixing tests * fixing indentation * Fixing com command * Fixing typo --- .../mapdl/core/_commands/apdl/array_param.py | 7 - .../mapdl/core/_commands/apdl/macro_files.py | 5 +- .../mapdl/core/_commands/apdl/matrix_op.py | 5 +- .../_commands/apdl/parameter_definition.py | 86 +------- .../mapdl/core/_commands/session/files.py | 31 +-- .../core/_commands/session/list_controls.py | 4 +- .../solution/load_step_operations.py | 4 +- src/ansys/mapdl/core/mapdl.py | 188 +++++++++++++++++- src/ansys/mapdl/core/misc.py | 2 +- tests/test_mapdl.py | 71 ++++++- 10 files changed, 264 insertions(+), 139 deletions(-) diff --git a/src/ansys/mapdl/core/_commands/apdl/array_param.py b/src/ansys/mapdl/core/_commands/apdl/array_param.py index 8c3ee71089..248d1831b0 100644 --- a/src/ansys/mapdl/core/_commands/apdl/array_param.py +++ b/src/ansys/mapdl/core/_commands/apdl/array_param.py @@ -1479,12 +1479,5 @@ def vwrite( This command is valid in any processor. """ - # cannot be in interactive mode - if not self._store_commands: - raise MapdlRuntimeError( - "VWRTIE cannot run interactively. \n\nPlease use " - "``with mapdl.non_interactive:``" - ) - command = f"*VWRITE,{par1},{par2},{par3},{par4},{par5},{par6},{par7},{par8},{par9},{par10},{par11},{par12},{par13},{par14},{par15},{par16},{par17},{par18},{par19}" return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/macro_files.py b/src/ansys/mapdl/core/_commands/apdl/macro_files.py index 92a427e3c8..961f0a4c75 100644 --- a/src/ansys/mapdl/core/_commands/apdl/macro_files.py +++ b/src/ansys/mapdl/core/_commands/apdl/macro_files.py @@ -565,7 +565,4 @@ def use( This command is valid in any processor. """ command = f"*USE,{name},{arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9},{ar10},{ar11},{ar12},{ar13},{ar14},{ag15},{ar16},{ar17},{ar18}" - with self.non_interactive: - self.run(command, **kwargs) - - return self._response # returning last response + return self.run(command, **kwargs) diff --git a/src/ansys/mapdl/core/_commands/apdl/matrix_op.py b/src/ansys/mapdl/core/_commands/apdl/matrix_op.py index 3ef2eb317a..18d03f7382 100644 --- a/src/ansys/mapdl/core/_commands/apdl/matrix_op.py +++ b/src/ansys/mapdl/core/_commands/apdl/matrix_op.py @@ -710,11 +710,8 @@ def nrm(self, name="", normtype="", parr="", normalize="", **kwargs): to the L1 norm and is applicable to vectors only. The NRMINF option is the maximum norm and is applicable to either vectors or matrices. """ - if not parr: - parr = "__temp_par__" command = f"*NRM,{name},{normtype},{parr},{normalize}" - self.run(command, **kwargs) - return self.parameters[parr] + return self.run(command, **kwargs) def remove(self, name="", val1="", val2="", val3="", **kwargs): """Suppresses rows or columns of a dense matrix or a vector. diff --git a/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py b/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py index 0504307d11..207fa827f0 100644 --- a/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py +++ b/src/ansys/mapdl/core/_commands/apdl/parameter_definition.py @@ -1,6 +1,3 @@ -import os - - class ParameterDefinition: def afun(self, lab="", **kwargs): """Specifies units for angular functions in parameter expressions. @@ -432,50 +429,7 @@ def inquire(self, strarray="", func="", arg1="", arg2=""): >>> mapdl.inquire('', 'RSTFILE') 'file.rst' """ - func_options = [ - "LOGIN", - "DOCU", - "APDL", - "PROG", - "AUTH", - "USER", - "DIRECTORY", - "JOBNAME", - "RSTDIR", - "RSTFILE", - "RSTEXT", - "OUTPUT", - "ENVNAME", - "TITLE", - "EXIST", - "DATE", - "SIZE", - "WRITE", - "READ", - "EXEC", - "LINES", - ] - - if strarray.upper() in func_options and func.upper() not in func_options: - # Likely you are using the old ``_Mapdl.inquire`` implementation. - raise ValueError( - "Arguments of this method have changed. `Mapdl.inquire` now includes the optional `strarray` parameter " - f"as the first argument. Either use `inquire(func={strarray})`, or `inquire(" - ", {strarray})`" - ) - - if func == "": - func = "DIRECTORY" - - response = self.run(f"/INQUIRE,{strarray},{func},{arg1},{arg2}", mute=False) - if func.upper() in [ - "ENV", - "TITLE", - ]: # the output is multiline, we just need the last line. - response = response.splitlines()[-1] - if "=" in response: - return response.split("=")[1].strip() - return "" + return self.run(f"/INQUIRE,{strarray},{func},{arg1},{arg2}") def parres(self, lab="", fname="", ext="", **kwargs): """Reads parameters from a file. @@ -518,43 +472,7 @@ def parres(self, lab="", fname="", ext="", **kwargs): >>> mapdl.parres('parm.PARM') """ - if not fname: - fname = self.jobname - - fname = self._get_file_name( - fname=fname, ext=ext, default_extension="parm" - ) # Although documentation says `PARM` - - if self._mode == "grpc": # grpc mode - if self.is_local: - # It must be a file! - if os.path.isfile(fname): - # And it exist! - filename = os.path.join(os.getcwd(), fname) - elif fname in self.list_files(): # - # It exists in the Mapdl working directory - filename = os.path.join(self.directory, fname) - elif os.path.dirname(fname): - raise ValueError( - f"'{fname}' appears to be an incomplete directory path rather than a filename." - ) - else: - # Finally - raise FileNotFoundError(f"Unable to locate filename '{fname}'") - - else: - if not os.path.dirname(fname): - # might be trying to run a local file. Check if the - # file exists remotely. - if fname not in self.list_files(): - self.upload(fname, progress_bar=False) - else: - self.upload(fname, progress_bar=False) - filename = os.path.basename(fname) - else: - filename = fname - - return self.input(filename) + return self.run(f"PARRES, {lab}, {fname}, {ext}") def parsav(self, lab="", fname="", ext="", **kwargs): """Writes parameters to a file. diff --git a/src/ansys/mapdl/core/_commands/session/files.py b/src/ansys/mapdl/core/_commands/session/files.py index bb0c323f63..2fef06c84b 100644 --- a/src/ansys/mapdl/core/_commands/session/files.py +++ b/src/ansys/mapdl/core/_commands/session/files.py @@ -1,7 +1,5 @@ """These SESSION commands are for file operations, such as deleting, copying, and listing.""" -import os - class Files: def anstoasas(self, fname="", key="", **kwargs): @@ -505,34 +503,7 @@ def lgwrite(self, fname="", ext="", kedit="", remove_grpc_extra=True, **kwargs): K,2,2,0,0 """ - # always add extension to fname - if ext: - fname = fname + f".{ext}" - - # seamlessly deal with remote instances in gRPC mode - target_dir = None - is_grpc = "Grpc" in type(self).__name__ - if is_grpc and fname: - if not self._local and os.path.basename(fname) != fname: - target_dir, fname = os.path.dirname(fname), os.path.basename(fname) - - # generate the log and download if necessary - output = self.run(f"LGWRITE,{fname},,,{kedit}", **kwargs) - if not fname: - # defaults to .lgw - fname = self.jobname + ".lgw" - if target_dir is not None: - self.download(fname, target_dir=target_dir) - - # remove extra grpc /OUT commands - if remove_grpc_extra and is_grpc and target_dir: - filename = os.path.join(target_dir, fname) - with open(filename, "r") as fid: - lines = [line for line in fid if not line.startswith("/OUT")] - with open(filename, "w") as fid: - fid.writelines(lines) - - return output + return self.run(f"LGWRITE,{fname},{ext},,{kedit}") def starlist(self, fname="", ext="", **kwargs): """Displays the contents of an external, coded file. diff --git a/src/ansys/mapdl/core/_commands/session/list_controls.py b/src/ansys/mapdl/core/_commands/session/list_controls.py index 86c300b479..45c4cb455b 100644 --- a/src/ansys/mapdl/core/_commands/session/list_controls.py +++ b/src/ansys/mapdl/core/_commands/session/list_controls.py @@ -26,9 +26,7 @@ def com(self, comment="", **kwargs): This command is valid anywhere. """ - command = "/COM,%s" % (str(comment)) - if self.print_com and not self.mute and not kwargs.get("mute", False): - print(command) + command = f"/COM, {comment}" return self.run(command, **kwargs) def golist(self, **kwargs): diff --git a/src/ansys/mapdl/core/_commands/solution/load_step_operations.py b/src/ansys/mapdl/core/_commands/solution/load_step_operations.py index 988ea3ba05..30d2561bdf 100644 --- a/src/ansys/mapdl/core/_commands/solution/load_step_operations.py +++ b/src/ansys/mapdl/core/_commands/solution/load_step_operations.py @@ -188,9 +188,7 @@ def lssolve(self, lsmin="", lsmax="", lsinc="", **kwargs): >>> mapdl.lssolve(1, 2) """ - with self.non_interactive: - self.run(f"LSSOLVE,{lsmin},{lsmax},{lsinc}", **kwargs) - return self.last_response + return self.run(f"LSSOLVE,{lsmin},{lsmax},{lsinc}", **kwargs) def lswrite(self, lsnum="", **kwargs): """Writes load and load step option data to a file. diff --git a/src/ansys/mapdl/core/mapdl.py b/src/ansys/mapdl/core/mapdl.py index c64ca5b3b6..cf06cd6d7d 100644 --- a/src/ansys/mapdl/core/mapdl.py +++ b/src/ansys/mapdl/core/mapdl.py @@ -4768,7 +4768,11 @@ def use(self, *args, **kwargs): # Update arg because the path is no longer needed args = (base_name, *args[1:]) - return super().use(*args, **kwargs) + + with self.non_interactive: + super().use(*args, **kwargs) + + return self._response # returning last response @wraps(Commands.set) def set( @@ -5066,3 +5070,185 @@ def cmplot(self, label: str = "", entity: str = "", keyword: str = "", **kwargs) self.cmsel("s", "__tmp_cm__", entity=entity) self.components.select(cmps_names) return output + + @wraps(Commands.inquire) + def inquire(self, strarray="", func="", arg1="", arg2=""): + """Wraps original INQUIRE function""" + func_options = [ + "LOGIN", + "DOCU", + "APDL", + "PROG", + "AUTH", + "USER", + "DIRECTORY", + "JOBNAME", + "RSTDIR", + "RSTFILE", + "RSTEXT", + "OUTPUT", + "ENVNAME", + "TITLE", + "EXIST", + "DATE", + "SIZE", + "WRITE", + "READ", + "EXEC", + "LINES", + ] + + if strarray.upper() in func_options and func.upper() not in func_options: + # Likely you are using the old ``_Mapdl.inquire`` implementation. + raise ValueError( + "Arguments of this method have changed. `Mapdl.inquire` now includes the optional `strarray` parameter " + f"as the first argument. Either use `inquire(func={strarray})`, or `inquire(" + ", {strarray})`" + ) + + if func == "": + func = "DIRECTORY" + + if strarray.upper() not in func_options and func.upper() not in func_options: + raise ValueError( + f"The arguments (strarray='{strarray}', func='{func}') are not valid." + ) + + response = self.run(f"/INQUIRE,{strarray},{func},{arg1},{arg2}", mute=False) + if func.upper() in [ + "ENV", + "TITLE", + ]: # the output is multiline, we just need the last line. + response = response.splitlines()[-1] + + return response.split("=")[1].strip() + + @wraps(Commands.parres) + def parres(self, lab="", fname="", ext="", **kwargs): + """Wraps the original /PARRES function""" + if not fname: + fname = self.jobname + + fname = self._get_file_name( + fname=fname, ext=ext, default_extension="parm" + ) # Although documentation says `PARM` + + # Getting the path for local/remote + filename = self._get_file_path(fname, progress_bar=False) + + return self.input(filename) + + @wraps(Commands.lgwrite) + def lgwrite(self, fname="", ext="", kedit="", remove_grpc_extra=True, **kwargs): + """Wraps original /LGWRITE""" + + # always add extension to fname + if ext: + fname = fname + f".{ext}" + + # seamlessly deal with remote instances in gRPC mode + target_dir = None + is_grpc = "Grpc" in type(self).__name__ + if is_grpc and fname: + if not self._local and os.path.basename(fname) != fname: + target_dir, fname = os.path.dirname(fname), os.path.basename(fname) + + # generate the log and download if necessary + output = super().lgwrite(fname=fname, kedit=kedit, **kwargs) + + if not fname: + # defaults to .lgw + fname = self.jobname + ".lgw" + if target_dir is not None: + self.download(fname, target_dir=target_dir) + + # remove extra grpc /OUT commands + if remove_grpc_extra and is_grpc and target_dir: + filename = os.path.join(target_dir, fname) + with open(filename, "r") as fid: + lines = [line for line in fid if not line.startswith("/OUT")] + with open(filename, "w") as fid: + fid.writelines(lines) + + return output + + @wraps(Commands.vwrite) + def vwrite( + self, + par1="", + par2="", + par3="", + par4="", + par5="", + par6="", + par7="", + par8="", + par9="", + par10="", + par11="", + par12="", + par13="", + par14="", + par15="", + par16="", + par17="", + par18="", + par19="", + **kwargs, + ): + """Wrapping *VWRITE""" + + # cannot be run in interactive mode + if not self._store_commands: + raise MapdlRuntimeError( + "VWRTIE cannot run interactively. \n\nPlease use " + "``with mapdl.non_interactive:``" + ) + + return super().vwrite( + par1=par1, + par2=par2, + par3=par3, + par4=par4, + par5=par5, + par6=par6, + par7=par7, + par8=par8, + par9=par9, + par10=par10, + par11=par11, + par12=par12, + par13=par13, + par14=par14, + par15=par15, + par16=par16, + par17=par17, + par18=par18, + par19=par19, + **kwargs, + ) + + @wraps(Commands.nrm) + def nrm(self, name="", normtype="", parr="", normalize="", **kwargs): + """Wraps *NRM""" + if not parr: + parr = "__temp_par__" + super().nrm( + name=name, normtype=normtype, parr=parr, normalize=normalize, **kwargs + ) + return self.parameters[parr] + + @wraps(Commands.com) + def com(self, comment="", **kwargs): + """Wraps /COM""" + if self.print_com and not self.mute and not kwargs.get("mute", False): + print("/COM,%s" % (str(comment))) + + return super().com(comment=comment, **kwargs) + + @wraps(Commands.lssolve) + def lssolve(self, lsmin="", lsmax="", lsinc="", **kwargs): + """Wraps LSSOLVE""" + with self.non_interactive: + super().lssolve(lsmin=lsmin, lsmax=lsmax, lsinc=lsinc, **kwargs) + return self.last_response diff --git a/src/ansys/mapdl/core/misc.py b/src/ansys/mapdl/core/misc.py index 94268eca81..e30b3ddaa8 100644 --- a/src/ansys/mapdl/core/misc.py +++ b/src/ansys/mapdl/core/misc.py @@ -844,7 +844,7 @@ def title(self): @title.setter def title(self, title): - return self._mapdl.title(title) + return self._mapdl.run(f"/TITLE, {title}") @property @update_information_first(True) diff --git a/tests/test_mapdl.py b/tests/test_mapdl.py index e46df07a95..e7b311b3a3 100644 --- a/tests/test_mapdl.py +++ b/tests/test_mapdl.py @@ -212,12 +212,45 @@ def test_global_mute(mapdl): def test_parsav_parres(mapdl, cleared, tmpdir): arr = np.random.random((10, 3)) + mapdl.parameters["MYARR"] = arr - mapdl.parsav("ALL", "tmp.txt") + mapdl.parsav("ALL", "db.txt") + mapdl.download("db.txt") + + # Restoring mapdl.clear() - mapdl.parres("ALL", "tmp.txt") + mapdl.parres("ALL", "db.txt") assert np.allclose(mapdl.parameters["MYARR"], arr) + # test no filename + mapdl.clear() + mapdl.parameters["MYARR"] = arr + mapdl.parsav("ALL") + + mapdl.clear() + mapdl.parres("ALL") + assert np.allclose(mapdl.parameters["MYARR"], arr) + + # Test upload local + mapdl.clear() + if "db.txt" in mapdl.list_files(): + mapdl.slashdelete("db.txt") + + mapdl.parres("NEW", "db", "txt") + assert np.allclose(mapdl.parameters["MYARR"], arr) + + # Test directory error + mapdl.clear() + with pytest.raises(FileNotFoundError): + mapdl.parres("NEW", os.getcwd()) + + # Test non-existing file + mapdl.clear() + with pytest.raises(FileNotFoundError): + mapdl.parres("change", "mydummy", "file") + + os.remove("db.txt") + @requires("grpc") def test_no_results(mapdl, cleared, tmpdir): @@ -2119,6 +2152,40 @@ def test_saving_selection_context(mapdl, cube_solve): assert "nod_selection_4" not in mapdl.components +def test_inquire_invalid(mapdl): + with pytest.raises(ValueError, match="Arguments of this method have changed"): + mapdl.inquire("directory") + + with pytest.raises(ValueError, match="The arguments "): + mapdl.inquire("dummy", "hi") + + +def test_inquire_default(mapdl): + mapdl.title = "heeeelloo" + assert mapdl.directory == mapdl.inquire() + + +def test_vwrite_error(mapdl): + with pytest.raises(MapdlRuntimeError): + mapdl.vwrite("adf") + + +def test_vwrite(mapdl): + with mapdl.non_interactive: + mapdl.run("/out,test_vwrite.txt") + mapdl.vwrite("'hello'") + mapdl.run("(1X, A8)") + mapdl.run("/out") + + mapdl.download("test_vwrite.txt") + + with open("test_vwrite.txt", "r") as fid: + content = fid.read() + + assert "hello" == content.strip() + os.remove("test_vwrite.txt") + + def test_get_array_non_interactive(mapdl, solved_box): mapdl.allsel() with pytest.raises(MapdlRuntimeError): From 67f9cb07b9fd6a6429f0d731a7c4845bbaf119f7 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 12:04:30 +0100 Subject: [PATCH 4/5] Adding missing envvar for connection commands in CICD (#2380) * Adding env var to container launcher. Activating tests * Adding env var to local Activating catia test * activating all tests so I can revaluate * activating all tests so I can revaluate * reverting to main --- .ci/start_mapdl.sh | 1 + .ci/start_mapdl_ubuntu.sh | 1 + .github/workflows/ci.yml | 1 + 3 files changed, 3 insertions(+) diff --git a/.ci/start_mapdl.sh b/.ci/start_mapdl.sh index 170f7c0284..3ce2377674 100755 --- a/.ci/start_mapdl.sh +++ b/.ci/start_mapdl.sh @@ -14,6 +14,7 @@ docker run \ -p $PYMAPDL_DB_PORT:50055 \ --shm-size=1gb \ -e I_MPI_SHM_LMT=shm \ + -e P_SCHEMA=/ansys_inc/ansys/ac4/schema \ --oom-kill-disable \ --memory=6656MB \ --memory-swap=16896MB \ diff --git a/.ci/start_mapdl_ubuntu.sh b/.ci/start_mapdl_ubuntu.sh index 2e3f511dae..08dfd9b4ca 100755 --- a/.ci/start_mapdl_ubuntu.sh +++ b/.ci/start_mapdl_ubuntu.sh @@ -15,6 +15,7 @@ docker run \ -p $PYMAPDL_DB_PORT:50055 \ --shm-size=1gb \ -e I_MPI_SHM_LMT=shm \ + -e P_SCHEMA=/ansys_inc/v222/ansys/ac4/schema \ -w /jobs \ -u=0:0 \ --oom-kill-disable \ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3f7c465643..86504f3c1d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -477,6 +477,7 @@ jobs: env: ON_LOCAL: true ON_UBUNTU: true + P_SCHEMA: "/ansys_inc/v222/ansys/ac4/schema" PYTEST_TIMEOUT: 120 # seconds. Limit the duration for each unit test steps: From e1034f32584eaed2c9059584be9aa71704f5206d Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 21 Nov 2023 12:22:11 +0100 Subject: [PATCH 5/5] API and contribution sections small reorganization (#2491) * API reog. Extended documentation about writing example and developing PyMAPDL. * Apply suggestions from code review Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update doc/source/getting_started/develop_pymapdl.rst * Update doc/source/links.rst * Simplifying accept file * fixing title --------- Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> Co-authored-by: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- doc/source/api/building_example.rst | 92 ----- doc/source/api/index.rst | 2 - doc/source/api/unit_testing.rst | 174 --------- doc/source/getting_started/contribution.rst | 142 +++----- .../getting_started/develop_pymapdl.rst | 335 ++++++++++++++++++ .../getting_started/write_documentation.rst | 232 ++++++++++++ doc/source/links.rst | 10 + doc/source/user_guide/troubleshoot.rst | 3 +- doc/styles/Vocab/ANSYS/accept.txt | 13 +- 9 files changed, 637 insertions(+), 366 deletions(-) delete mode 100644 doc/source/api/building_example.rst delete mode 100644 doc/source/api/unit_testing.rst create mode 100644 doc/source/getting_started/develop_pymapdl.rst create mode 100644 doc/source/getting_started/write_documentation.rst diff --git a/doc/source/api/building_example.rst b/doc/source/api/building_example.rst deleted file mode 100644 index ee5d1f9a04..0000000000 --- a/doc/source/api/building_example.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. _ref_building_example: - - -=================== -Building an example -=================== - -.. currentmodule:: ansys.mapdl.core.building_example - -To run the documentation, you need to have the correct versions of each tool. To do so, execute the -following instruction. - -.. code:: console - - pip install -r requirements/requirements_docs.txt - - -The Sphinx configuration is in the file -`conf.py `_ in :file:`doc/source`. - - -To run the sphinx tool: - -.. code:: pwsh-session - - doc\make.bat html - - -There are three types of examples: dynamic, static, and semi-static. - -* `Dynamic examples`_ -* `Static examples`_ -* `Semi-dynamic examples`_ - - -Dynamic examples ----------------- - -The dynamic examples are based on Python files and must be able to run in under three minutes. - -They are in the `examples `_ directory in this repository. - -.. vale off - -Example: `2d_plate_with_a_hole.py `_ -.. vale on - -Here is a link to this dynamic example: -`MAPDL 2D Plane Stress Concentration Analysis `_ - -When an example is executed, **Total running time of the script** appears at the end of -the document. - - -Static examples ---------------- - -Static examples are based on RST files and are not executed. - -They are in the `doc\source `_ directory. -.. vale off - -Example: `krylov_example.rst `_ -.. vale on - -Here is a link to this static example: `Harmonic analysis using the frequency-sweep Krylov method `_ - - -Semi-dynamic examples ---------------------- - -Semi-dynamic examples are RST files that execute Python code using this RST directive: - -.. code:: rst - - .. jupyter-execute:: - :hide-code: - - -.. vale off - -Example: `tecfricstir.rst `_ -.. vale on - -Here is a link to this semi-dynamic example: `Friction Stir Welding (FSW) Simulation `_ - - -Recommendations ---------------- - -As dynamic examples must run each time documentation is built, make sure that they are very short. -To get around the problem of execution time, feel free to use static or semi-static examples. diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index e452fe45ff..459792ce43 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -36,5 +36,3 @@ PyMAPDL, see :ref:`ref_mapdl_commands`. Pyansys Math solution xpl - building_example - unit_testing diff --git a/doc/source/api/unit_testing.rst b/doc/source/api/unit_testing.rst deleted file mode 100644 index 74ac56865b..0000000000 --- a/doc/source/api/unit_testing.rst +++ /dev/null @@ -1,174 +0,0 @@ -.. _ref_unit_testing_contributing: - -Unit testing -============ - -Unit tests validate the software by testing that the logic -implemented inside a certain method, class, or module is -working as expected. They should be as atomic and -independent as possible. - -Unit testing is highly important. The tests verify that code -changes are consistent with other parts of the code -and verify that these changes are implemented properly. - -Unit tests are in the `tests `_ directory in this repository, -along with integration tests. The difference between -a unit test and an integration test is that the latter -tests several units of the code to ensure that they all work together. - -To verify that all code is properly tested, you must ensure that every piece -of code is used (covered) in at least one unit test. In this repository, the -`Codecov `_ tool generates a coverage report of the -committed code. It details how merging a pull request would impact coverage. It -is one of the checks that must run successfully to merge code changes. - - -.. figure:: ../images/codecov_increase.png - :width: 400pt - - -Coverage example ----------------- - -To show how the coverage works, assume that you have -this library: - -**Awesome library** - - -.. code:: python - - def get_report_colors(theme): - if theme == "weather": - colors = ["blue", "lightblue", "grey"] - elif theme == "traffic": - colors = ["red", "orange", "yellow"] - else: - colors = ["red", "blue", "green"] - - return colors - - -**Tests** - -You can opt to run the tests with this configuration: - -.. code:: python - - def test_get_report_colors(): - assert get_report_colors("weather") == ["blue", "lightblue", "grey"] - assert get_report_colors("traffic") == ["red", "orange", "yellow"] - assert get_report_colors("other") == ["red", "blue", "green"] - - -Or, if a method is a bit more complex, you can split the case in different tests: - -.. code:: python - - def test_get_report_colors_weather(): - assert get_report_colors("weather") == ["blue", "lightblue", "grey"] - - - def test_get_report_colors_traffic(): - assert get_report_colors("traffic") == ["red", "orange", "yellow"] - - - def test_get_report_colors_other(): - assert get_report_colors("other") == ["red", "blue", "green"] - - -While the code coverage in either case is 100% for the function, the second case is -more useful for debugging the function. - - -Continuous Integration and Continuous Deployment (CI/CD) approach ------------------------------------------------------------------ - -Unit tests and integration tests are part of Continuous Integration (CI). -The automation of testing, monitoring, and deployment of newly added -code allows Continuous Deployment (CD) throughout the app lifecycle, -providing a comprehensive CI/CD approach. - -.. figure:: ../images/cicd.jpg - :width: 300pt - -Creation of a unit test ------------------------ - -In the PyMAPDL repository, `pytest `_ is used to run tests. - -The name of a ``pytest`` file must be in the form ``test_XXX.py``, where ``XXX`` -is either the function, method, or class that you are testing or some other explicative -name. In the command line, the ``-k`` argument can be used to filter the tests to run. -For more information, see `pytest usage `_. - -Here are some guidelines for creating good unit tests: - -- Assign long and descriptive names to tests. -- Use the `Codecov `_ tool to ensure all implemented code is tested. -- Check that tests return the same results each time. -- Verify that tests are independent. -- Write tests that verify only one part of the code at a time. -- Make tests as short and fast as possible. - -`What makes a good unit test `_ -is an exhaustive list of tips for creating good unit tests. - -Most PyMAPDL tests require a connection to a running instance of -MAPDL, which makes them integration tests. If your test -requires a running MAPDL instance, you can use the PyMAPDL -`mapdl `_ method in your function signature. -It is executed upstream of each test and not within all tests. - -.. code:: python - - def test_my_new_feature(mapdl): # pass the 'mapdl' fixture as an argument. - mapdl.prep7() - # .... more code - - return True # if everything goes ok until here - - -Example --------- - -.. TO BE MODIFIED - -The `test_component.py `_ file contains -the unit tests and integration tests of the -:class:`ComponentManager `. -These are just some of the many tests that you can find in the -`test directory `_. - -Here are some examples of how you use ``pytest``: - -.. code:: python - - import pytest - - - # 'cube_geom_and_mesh' is another fixture defined in 'conftest.py' - @pytest.fixture(scope="function") - def basic_components(mapdl, cube_geom_and_mesh): - """Given a model in 'cube_geom_and_mesh', let's define some components to work with later.""" - mapdl.components["mycomp1"] = "NODE", [1, 2, 3] - mapdl.components["mycomp2"] = "KP", [1, 3] - - mapdl.cmsel("s", "mycomp1") - mapdl.cmsel("a", "mycomp2") - - - def test_dunder_methods_keys(mapdl, basic_components): - assert ["MYCOMP1", "MYCOMP2"] == list(mapdl.components.names()) - - - def test_dunder_methods_types(mapdl, basic_components): - assert ["NODE", "KP"] == list(mapdl.components.types()) - - - def test_dunder_methods_items(mapdl, basic_components): - assert [("MYCOMP1", "NODE"), ("MYCOMP2", "KP")] == list(mapdl.components.items()) - - -For further explanations, see the `pytest documentation `_. \ No newline at end of file diff --git a/doc/source/getting_started/contribution.rst b/doc/source/getting_started/contribution.rst index 8c2662d325..4ed5b5b194 100644 --- a/doc/source/getting_started/contribution.rst +++ b/doc/source/getting_started/contribution.rst @@ -4,106 +4,70 @@ Contributing ============ -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 -with it and all `Coding style `_ before attempting to -contribute to PyMAPDL. - -The following contribution information is specific to PyMAPDL. +.. toctree:: + :hidden: + :maxdepth: 3 -Cloning the PyMAPDL repository -============================== + write_documentation + develop_pymapdl -Run this code to clone and install the latest version of PyMAPDL in development mode: -.. code:: console +There are several ways to contribute to PyMAPDL. - git clone https://github.com/ansys/pymapdl - cd pymapdl - pip install pip -U - pip install -e . +* `Answer discussions`_ +* `Post issues`_ +* :ref:`write_documentation` +* :ref:`developing_pymapdl` +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 +with it and the `Coding style `_ before attempting to +contribute to PyMAPDL. + -Posting issues -============== - -Use the `PyMAPDL Issues `_ -page to submit questions, report bugs, and request new features. When possible, -use these issue templates: +Answer discussions +================== + +Answering discussions is an excellent way to contribute to PyMAPDL, and +it does not require any setup, just a GitHub account. +It is probably the first step towards becoming a full PyMAPDL developer, since it +helps you deepen your understanding of the project. Engaging in +discussions often requires a thorough grasp of the project's goals and +challenges. +Your contributions can help other users or contributors who +may be facing similar issues, making the repository more welcoming and +inclusive. By providing answers or solutions, you can directly contribute to the project's +success, maintain its health, and encourage a positive, open source ecosystem. + +To discover how you can help, see the `PyMAPDL Discussions `_ page. + + +Post issues +=========== + +Posting issues in a repository is a valuable contribution that benefits you, the +repository, and PyMAPDL as a whole. It allows you to voice concerns, suggest +improvements, or report bugs, which can lead to a more robust and user-friendly +project. It also offers an opportunity for you to engage with the project's +community, learn from others, and gain experience in issue tracking and +collaboration. +For the repository, issues serve as a structured way to track and +prioritize work, helping maintainers understand the needs of users and guide the +project's development. It's an excellent way to contribute because it enhances +the project's quality, fosters transparency, and encourages the collective +effort of the community to continuously improve and innovate. + +Use the `PyMAPDL Issues `_ page to submit questions, report bugs, +and request new features. +When possible, use these issue templates: * **🐞 Bug, problem, or error**: Fill a bug report here * **📖 Documentation issue**: Modifications to the documentation only * **🎓 Adding an example**: Proposing a new example for the library * **💡 New feature**: Enhancements to the code -If your issue does not fit into one of these categories, click in `Open a blank issue `_. - - -Viewing PyMAPDL documentation -============================= - -Documentation for the latest stable release of PyMAPDL is hosted at -`PyMAPDL Documentation `_. - -In the upper right corner of the documentation's title bar, there is an option -for switching from viewing the documentation for the latest stable release -to viewing the documentation for the development version or previously -released versions. - -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. - -**On Windows** - -.. code:: pwsh-session - - SET PYMAPDL_START_INSTANCE=False - SET PYMAPDL_PORT= (default 50052) - SET PYMAPDL_IP= (default 127.0.0.1) - -**On Linux** - -.. code:: console - - export PYMAPDL_START_INSTANCE=False - export PYMAPDL_PORT= (default 50052) - export PYMAPDL_IP= (default 127.0.0.1) - -This tells ``ansys.mapdl.core`` to attempt to connect to the existing -MAPDL service by default when the ``launch_mapdl`` function is used. - -Additionally you can use the environment variables ``PYMAPDL_MAPDL_EXEC`` -and ``PYMAPDL_MAPDL_VERSION`` to specify MAPDL executable path and the -version to launch (if multiple versions of MAPDL are installed). - - -Code style -========== - -PyMAPDL follows PEP8 standard as outlined in the `PyAnsys Development Guide -`_ and implements style checking using -`pre-commit `_. - -To ensure your code meets minimum code styling standards, run:: - - pip install pre-commit - pre-commit run --all-files - -You can also install this as a pre-commit hook by running:: - - pre-commit install - -This way, it's not possible for you to push code that fails the style checks. For example:: - - $ pre-commit install - $ git commit -am "added my cool feature" - black....................................................................Passed - isort....................................................................Passed - flake8...................................................................Passed - codespell................................................................Passed +If your issue does not fit into one of these categories, click +`Open a blank issue `_. \ No newline at end of file diff --git a/doc/source/getting_started/develop_pymapdl.rst b/doc/source/getting_started/develop_pymapdl.rst new file mode 100644 index 0000000000..0d4c19c507 --- /dev/null +++ b/doc/source/getting_started/develop_pymapdl.rst @@ -0,0 +1,335 @@ + +.. _developing_pymapdl: + +============ +Develop code +============ + +You can help improve PyMAPDL by fixing a bug or developing a new feature. +To do either, you must set up the repository on your local machine as per the +explanations in the following sections. + + +Clone the PyMAPDL repository +============================ + +Before cloning the PyMAPDL repository, you must install a version control system such as Git. +You can this run this code to clone the latest development version of PyMAPDL: + +.. code:: console + + git clone https://github.com/ansys/pymapdl + cd pymapdl + + + +Create a Python virtual environment +=================================== + +To avoid dependency conflicts and more easily manage upgrades, you should install PyMAPDL in its own virtual environment. For detailed information on how to install Python and create a virtual environment, see +`Setting up your development environment `_. + +Install PyMAPDL in development mode +=================================== + +Install the latest version of PyMAPDL in development mode with these commands: + + +.. code:: console + + cd pymapdl + pip install pip -U + pip install -e . + + +If you are going to do testing, you must install the testing dependencies with this command: + + +.. code:: console + + pip install -e '.[tests]' + + +Develop PyMAPDL +=============== + +.. epigraph:: *Now it is time to develop PyMAPDL!* + +Developing code in a repository, particularly when using version control systems +like Git, involves a set of essential guidelines to ensure efficient +collaboration, code management, and tracking changes. Here are the main +guidelines for developing code in a repository: + +#. **Use branches**: Create branches for different features, bug fixes, or + experiments. This keeps changes isolated and facilitates parallel + development. + +#. **Write descriptive commit messages**: Provide clear and concise commit + messages that explain the purpose and context of the changes. Follow a + consistent style. + +#. **Commit frequently**: Make small, meaningful commits frequently. Avoid + making a large number of unrelated changes in a single commit. + +#. **Pull before you push**: Always update your local branch with the latest + changes from the remote repository before pushing your own changes to avoid + conflicts. + +#. **Use pull requests (PRs)**: Use PRs to submit your changes for review. + This allows for discussion and validation before merging into the main branch. + +#. **Write good documentation**: Maintain clear and up-to-date documentation for your + contribution or changes, including comments in code, and relevant project + documentation in rST or Markdown files. + If you implement a new feature or change the behaviour of the library in any way, + remember to mention it somewhere in the documentation (rST files in :file:`doc\source` directory) + Follow the `numpydoc `_ convention for documenting code. + +#. **Test your changes**: Thoroughly test your changes to ensure that they work + as expected. If applicable, create or update the unit tests that run on the + continuous integration/continuous deployment (CI/CD) pipelines to catch issues early + and ensure reliable deployments. For more information, see `Unit testing`_. + +#. **Respect code style and standards**: Follow code style + guidelines and adhere to coding standards specific to your language or + framework. + +#. **Collaborate and communicate**: Communicate with team members, provide + updates on your progress, and resolve any conflicts promptly. + +#. **Ask for help**: To ensure code quality, identify issues, and share knowledge, + ask PyMAPDL developers to assist you and review your code. + If you need help or guidance, mention ``@ansys/pymapdl-maintainers`` in a comment + so they they are notified. + +By following these guidelines, you can ensure smooth and organized code +development within a repository, fostering collaboration, code quality, and feature enhancement. + + +.. _ref_unit_testing_contributing: + +Unit testing +============ + +Unit tests validate the software by testing that the logic implemented inside a +certain method, class, or module is working as expected. They should be as +atomic and independent as possible. + +Unit testing is highly important. The tests verify that code changes are +consistent with other parts of the code and verify that these changes are +implemented properly. + +Unit tests are in the `tests `_ directory in this repository, +along with integration tests. The difference between a unit test and an +integration test is that the latter tests several units of the code to ensure +that they all work together. + +To verify that all code is properly tested, you must ensure that every piece of +code is used (covered) in at least one unit test. In this repository, the +`Codecov `_ tool generates a coverage report of the committed code. It +indicates how merging a pull request would impact coverage. The generation of this report is one of the +checks that must run successfully to merge code changes. + + +.. figure:: ../images/codecov_increase.png + :width: 400pt + + +Coverage example +---------------- + +To show how the coverage works, assume that you have +this library: + +**Awesome library** + + +.. code:: python + + def get_report_colors(theme): + if theme == "weather": + colors = ["blue", "lightblue", "grey"] + elif theme == "traffic": + colors = ["red", "orange", "yellow"] + else: + colors = ["red", "blue", "green"] + + return colors + + +**Tests** + +You can opt to run the tests with this configuration: + +.. code:: python + + def test_get_report_colors(): + assert get_report_colors("weather") == ["blue", "lightblue", "grey"] + assert get_report_colors("traffic") == ["red", "orange", "yellow"] + assert get_report_colors("other") == ["red", "blue", "green"] + + +Or, if a method is a bit more complex, you can split the case in different tests: + +.. code:: python + + def test_get_report_colors_weather(): + assert get_report_colors("weather") == ["blue", "lightblue", "grey"] + + + def test_get_report_colors_traffic(): + assert get_report_colors("traffic") == ["red", "orange", "yellow"] + + + def test_get_report_colors_other(): + assert get_report_colors("other") == ["red", "blue", "green"] + + +While the code coverage in either case is 100% for the function, the second case is +more useful for debugging the function. + + +Continuous integration and continuous deployment +------------------------------------------------ + +Unit tests and integration tests are part of continuous integration (CI). +The automation of testing, monitoring, and deployment of newly added +code allows continuous deployment (CD) throughout the app lifecycle, +providing a comprehensive CI/CD approach. + +.. figure:: ../images/cicd.jpg + :width: 300pt + +Creation of a unit test +----------------------- + +In the PyMAPDL repository, `pytest `_ is used to run tests. + +The name of a ``pytest`` file must be in the form ``test_XXX.py``, where ``XXX`` +is either the function, method, or class that you are testing or some other explicative +name. In the command line, you can use the ``-k`` argument to filter the tests to run. +For more information, see `pytest usage `_. + +Here are some guidelines for creating good unit tests: + +- Assign long and descriptive names to tests. +- Use the `Codecov `_ tool to ensure that all implemented code is tested. +- Check that tests return the same results each time. +- Verify that tests are independent. +- Write tests that verify only one part of the code at a time. +- Make tests as short and fast as possible. + +`What makes a good unit test? `_ +is an exhaustive list of tips for creating good unit tests. + +Most PyMAPDL tests require a connection to a running instance of +MAPDL, which makes them integration tests. If your test +requires a running MAPDL instance, you can use the PyMAPDL +`mapdl `_ method in your function signature. +It is executed upstream of each test and not within all tests. + +.. code:: python + + def test_my_new_feature(mapdl): # pass the 'mapdl' fixture as an argument. + mapdl.prep7() + # .... more code + + return True # if everything goes ok until here + + +If you do not have MAPDL installed locally but still want to run the +unit testing, you must set up the following environment variables. + +In Windows, use this code: + +.. code:: pwsh-session + + SET PYMAPDL_START_INSTANCE=False + SET PYMAPDL_PORT= (default 50052) + SET PYMAPDL_IP= (default 127.0.0.1) + +In Linux, use this code: + +.. code:: console + + export PYMAPDL_START_INSTANCE=False + export PYMAPDL_PORT= (default 50052) + export PYMAPDL_IP= (default 127.0.0.1) + +These environment variables tell PyMAPDL to attempt to connect to the existing +MAPDL service by default when the ``launch_mapdl`` function is used. + +Additionally, you can use the :envvar:`PYMAPDL_MAPDL_EXEC` and :envvar:`PYMAPDL_MAPDL_VERSION` +environment variables to specify the MAPDL executable path and the version to launch (if +multiple versions of MAPDL are installed). + + +Example +-------- + +.. TO BE MODIFIED + +The `test_component.py `_ file contains +the unit tests and integration tests for the +:class:`ComponentManager ` class. +These tests are just some of the many in the `test directory `_. + +Here are some examples of how you use ``pytest``: + +.. code:: python + + import pytest + + + # 'cube_geom_and_mesh' is another fixture defined in 'conftest.py' + @pytest.fixture(scope="function") + def basic_components(mapdl, cube_geom_and_mesh): + """Given a model in 'cube_geom_and_mesh', define some components to work with later.""" + mapdl.components["mycomp1"] = "NODE", [1, 2, 3] + mapdl.components["mycomp2"] = "KP", [1, 3] + + mapdl.cmsel("s", "mycomp1") + mapdl.cmsel("a", "mycomp2") + + + def test_dunder_methods_keys(mapdl, basic_components): + assert ["MYCOMP1", "MYCOMP2"] == list(mapdl.components.names()) + + + def test_dunder_methods_types(mapdl, basic_components): + assert ["NODE", "KP"] == list(mapdl.components.types()) + + + def test_dunder_methods_items(mapdl, basic_components): + assert [("MYCOMP1", "NODE"), ("MYCOMP2", "KP")] == list(mapdl.components.items()) + + +For further explanations, see the `pytest documentation `_. + + + +Code style +========== + +PyMAPDL follows the PEP8 standard as outlined in the `PyAnsys Development Guide +`_ and implements style checking using +`pre-commit `_. + +To ensure your code meets minimum code styling standards, run these commands:: + + pip install pre-commit + pre-commit run --all-files + +You can also install this as a pre-commit hook by running this command:: + + pre-commit install + +This way, it's not possible for you to push code that fails the style checks. For example:: + + $ pre-commit install + $ git commit -am "added my cool feature" + black....................................................................Passed + isort....................................................................Passed + flake8...................................................................Passed + codespell................................................................Passed + diff --git a/doc/source/getting_started/write_documentation.rst b/doc/source/getting_started/write_documentation.rst new file mode 100644 index 0000000000..7b03e0e9c4 --- /dev/null +++ b/doc/source/getting_started/write_documentation.rst @@ -0,0 +1,232 @@ +.. _write_documentation: + +=================== +Write documentation +=================== + +Writing documentation is an excellent way to contribute to a project because it +plays a pivotal role in making the project more accessible and usable. Clear and +comprehensive documentation empowers users and developers to understand, +implement, and troubleshoot the project effectively. It minimizes barriers to +entry, making it easier for newcomers to get involved and for existing +contributors to be more productive. + +Good documentation also reduces the burden on maintainers, +as it can answer common questions and help prevent issues. By +creating or improving documentation, you not only enhance the project's quality +but also facilitate knowledge sharing and community growth, making your +contribution invaluable for the project's long-term success. + +Set up your environment +======================= + +To be able to write and build the documentation, you must follow the same +steps described in :ref:`developing_pymapdl`, but in this case, you must install +documentation dependencies with this command: + +.. code:: console + + pip install -e '.[doc]' + + +Build the documentation +======================= + +PyMAPDL documentation is mainly written in reStructuredText +format, saved as ``.rst`` files in the ``doc/source`` directory. +The tool used to build the documentation from these reStructuredText files +is `Sphinx `_. + +Sphinx also build API documentation from source code as well as manages the +cross-referencing between different files, classes, methods, and more. +Additionally, it builds an `examples gallery `_, +where the capabilities of PyMAPDL can be showcased. + +The documentation can be built as HTML files or a single PDF file. + +To build the documentation as HTML files, you only need to run a single command. + +On Linux: + + +.. code:: console + + make -C doc html + +On Windows: + +.. code:: pwsh-session + + doc\make.bat html + +The HTML files for the documentation are written to the ``doc/_build/html`` directory. + +If you want to build the PDF documentation, you must first install +a LaTeX distribution like `MikTeX `_. You can then run this command: + +.. code:: console + + make -C doc pdf + +Running the command to build either HTML files or a PDF file runs the Python files in ``./examples`` in the repository root directory to generate the `examples gallery `_. +The result of running these examples is cached so that the only the changed files +are re-run the next time. + +The Sphinx configuration is in the file +`conf.py `_ in :file:`doc/source`. + + +Write documentation +=================== + +Writing good documentation for a GitHub repository is crucial to ensure that +users and contributors can understand, use, and contribute to PyMAPDL +effectively. + +Here's a short summary of how to write good documentation: + +#. **Use a consistent structure**: Organize your documentation with a clear and + consistent structure. Use headings, subheadings, and a table of contents if + necessary to help users navigate your documentation easily. + +#. **Explain configuration changes**: If you require configuration changes, provide + clear instructions on how to use this new configuration, along with examples and explanations + of why they are needed. + +#. **Usage Examples**: Include real-world usage examples, code snippets, and + explanations to demonstrate how users can make the most of PyMAPDL. + +#. **Document the API and code**: Thoroughly document each function, class, and method. Include + parameter descriptions, return values, and usage examples. Follow the + `numpydoc `_ convention for documenting code. + +#. **Tutorials and guides**: Create tutorials or guides to help users achieve + specific tasks or workflows with PyMAPDL. These can be especially + helpful for complex projects. + +#. **Troubleshooting and FAQs**: Anticipate common issues and provide solutions + in a troubleshooting section. Frequently asked questions (FAQs) can also be + helpful for addressing common queries. + +#. **Maintain and update**: Keep your documentation up to date as the project + evolves. New features, changes, and bug fixes should be reflected in the + documentation. + +#. **Solicit Feedback**: Invite users and contributors to provide feedback on + the documentation and be responsive to their suggestions and questions. + + +Vale linting tool +================= + +On the GitHub repository, the CI/CD runs `Vale `_, a powerful and extensible linting tool for +checking the writing of each pull request. +If you want to verify locally as well, you must install Vale locally: + +Installation +------------ + +#. **Install Vale**: Follow the instructions in `Installation `_ +#. **Verify installation**: To confirm that Vale is installed correctly, run this command: + + .. code:: console + + vale --version + + You should see the installed Vale version displayed in the terminal. + +Usage +----- + +Vale is a versatile tool for linting and style checking your documents, +supporting various file formats and providing a wide range of style guides. +Here's a basic example of how to use Vale in PyMAPDL: + +#. **Sync styles**: The first time you run Vale in a repository, you must + sync the styles specified in the :file:`.vale.ini` file by running this command: + + .. code:: console + + vale sync + + +#. **Lint Your Document**: To verify a document, run Vale from the command line, + specifying the file or directory you want to lint. For example: + + .. code:: console + + vale --config="./doc/.vale.ini" path/to/your_document.rst + + Vale analyzes your document, and if there are any style guide violations + or linting issues, it provides feedback in the terminal. + +Make sure you have no errors or warnings before opening your pull request. + + +.. _ref_building_example: + +Create an example +================= +There are three types of examples: dynamic, static, and semi-static. + +* `Dynamic examples`_ +* `Static examples`_ +* `Semi-dynamic examples`_ + + +Dynamic examples +---------------- + +Dynamic examples are based on Python files and must be able to run in under three minutes. + +In the PyMAPD repository, they are in the `examples `_ directory. + +.. vale off + +Example: `2d_plate_with_a_hole.py `_ +.. vale on + +Here is a link to this dynamic example: +`MAPDL 2D Plane Stress Concentration Analysis `_ + +When an example is executed, **Total running time of the script** appears at the end of +the document. + +Because dynamic examples must run each time the documentation is built, make sure that they are +very short. To get around the problem of execution time, feel free to use static or semi-static +examples. + + +Static examples +--------------- + +Static examples are based on RST files and are not executed. + +In the PyMAPDL repository, they are in the `doc\source `_ directory. +.. vale off + +Example: `krylov_example.rst `_ +.. vale on + +Here is a link to this static example: `Harmonic analysis using the frequency-sweep Krylov method `_ + + +Semi-dynamic examples +--------------------- + +Semi-dynamic examples are RST files that execute Python code using this RST directive: + +.. code:: rst + + .. jupyter-execute:: + :hide-code: + + +.. vale off + +Example: `tecfricstir.rst `_ +.. vale on + +Here is a link to this semi-dynamic example: `Friction Stir Welding (FSW) Simulation `_ + + diff --git a/doc/source/links.rst b/doc/source/links.rst index b1fb34392a..eb54e31635 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -22,6 +22,7 @@ .. _dev_guide_pyansys: https://dev.docs.pyansys.com .. _dev_guide_contributing: https://dev.docs.pyansys.com/how-to/contributing.html .. _dev_guide_coding_style: https://dev.docs.pyansys.com/coding-style/index.html +.. _dev_guide_setup_your_environment: https://dev.docs.pyansys.com/how-to/setting-up.html .. #Other libraries .. _pyvista_docs: https://docs.pyvista.org/version/stable/ @@ -108,6 +109,11 @@ .. _tds_article_web_app_1: https://towardsdatascience.com/ansys-in-a-python-web-app-part-1-post-processing-with-pydpf-44d2fbaa6135 .. _tds_article_web_app_2: https://towardsdatascience.com/ansys-in-a-python-web-app-part-2-pre-processing-solving-with-pymapdl-50428c18f8e7 .. _paraview_question_read_rst: https://discourse.paraview.org/t/reading-ansys-apdl-rst-results-in-paraview/9706 +.. _miktex: https://miktex.org +.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/ +.. _sphinx: https://www.sphinx-doc.org/en/master/ +.. _vale: https://www.vale.sh +.. _vale_installation: https://vale.sh/docs/vale-cli/installation/ .. #Github links: .. _gh_creating_pat: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token @@ -148,6 +154,10 @@ .. _pymapdl_discussion_differences_mapdl_pymapdl: https://github.com/ansys/pymapdl-reader/issues/185 .. _cartpole_example_notebook: https://cartpole.mapdl.docs.pyansys.com/ml-rl-notebook.html .. _wsl_launching_mapdl: https://github.com/ansys/pymapdl/issues/2315 +.. _pymapdl_examples_gallery: https://mapdl.docs.pyansys.com/version/stable/examples/index.html +.. _pymapdl_latest_github_release: https://github.com/ansys/pymapdl/releases/latest +.. _pymapdl_latest_pdf_doc: https://github.com/ansys/pymapdl/releases/download/v%%PYMAPDLVERSION%%.0/pymapdl-Documentation-%%PYMAPDLVERSION%%.0.pdf +.. _pymapdl_conf_file: https://github.com/ansys/pymapdl/blob/main/doc/source/conf.py .. _pymapdl_search_issues_pr: https://github.com/ansys/pymapdl/issues?q= .. _pymapdl_latest_github_release: https://github.com/ansys/pymapdl/releases/latest .. _pymapdl_latest_pdf_doc: https://github.com/ansys/pymapdl/releases/download/v%%PYMAPDLVERSION%%.0/pymapdl-Documentation-%%PYMAPDLVERSION%%.0.pdf diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index b007e0d9b0..38315fc3e9 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -34,8 +34,7 @@ script: 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 `_. +If you believe you have found a bug, create an issue on the `PyMAPDL Issues page `_. .. _ref_launching_issue: diff --git a/doc/styles/Vocab/ANSYS/accept.txt b/doc/styles/Vocab/ANSYS/accept.txt index de0ee6a543..df7a82e475 100644 --- a/doc/styles/Vocab/ANSYS/accept.txt +++ b/doc/styles/Vocab/ANSYS/accept.txt @@ -1,10 +1,12 @@ [aA]nsys [Bb]ooleans [Cc]ommand [Pp]rompt +[Dd]ocker [Ee]igensolver [Hh]yperelasticity [Kk]eypoints [Mm]atplotlib +[Mm]ulti-[Ff]ield [Nn]umpy [Pp]ostprocess [Pp]ostprocessing @@ -14,6 +16,8 @@ [Pp]yansys [Pp]ythonic [Pp]ythonically +[Rs]ST +[Ss]ubsystem [Ss]uperelements [Vv]on Mises 2D @@ -46,8 +50,6 @@ Chao container_layout datas delet -docker -Docker dof ect eigenfrequency @@ -69,8 +71,8 @@ GPa GUI hexahedral hostname -Imagemagick -ImageMagick +HTML +Image[Mm]agick imagin importlib ist @@ -93,7 +95,6 @@ midside Mises mkdir MSc -Multi-[Ff]ield multipoint nce Newton-Raphson @@ -126,7 +127,6 @@ Radiosity Rao righ RNNN -RST singl smal sord @@ -134,7 +134,6 @@ spotweld struc subselected substep -Subsystem sur tablet thermomechanical