docs: documenting using pymapdl on clusters

.github/workflows/ci.yml

@@ -34,6 +34,7 @@ env:
   MAPDL_PACKAGE: ghcr.io/ansys/mapdl
   ON_CI: True
   PYTEST_ARGUMENTS: '-vvv -ra --durations=10 --maxfail=3 --reruns 3 --reruns-delay 4 --cov=ansys.mapdl.core --cov-report=html'
+  BUILD_CHEATSHEET: True
 
   # Following env vars when changed will "reset" the mentioned cache,
   # by changing the cache file name. It is rendered as ...-v%RESET_XXX%-...

doc/changelog.d/3466.documentation.md

@@ -0,0 +1 @@
+feat: passing tight integration env vars to mapdl

doc/changelog.d/3468.fixed.md

@@ -0,0 +1 @@
+fix: add ``build cheatsheet`` as env variable within doc-build

doc/source/conf.py

@@ -311,13 +311,17 @@
         "json_url": f"https://{cname}/versions.json",
         "version_match": switcher_version,
     },
-    "cheatsheet": {
+}
+
+BUILD_CHEATSHEET = os.environ.get("BUILD_CHEATSHEET", "true").lower() == "true"
+
+if BUILD_CHEATSHEET:
+    html_theme_options["cheatsheet"] = {
         "file": "cheat_sheet/cheat_sheet.qmd",
         "title": "PyMAPDL cheat sheet",
         "version": f"v{version}",
         "pages": ["getting_started/learning"],
-    },
-}
+    }
 
 html_context = {
     "display_github": True,  # Integrate GitHub

doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst

@@ -251,7 +251,7 @@ this script.
 
    If you have problems when creating the virtual environment
    or accessing it from the compute nodes,
-   see :ref:`ref_hpc_pymapdl_job`.
+   see :ref:`ref_hpc_troubleshooting`.
 
 3. Install the requirements for this example from the
    :download:`requirements.txt <requirements.txt>` file.

doc/source/user_guide/hpc/pymapdl.rst

@@ -1,84 +1,169 @@
-.. _ref_hpc_pymapdl:
 
+.. _ref_hpc_pymapdl_job:
 
-=============================
-PyMAPDL on SLURM HPC clusters
-=============================
+=======================
+PyMAPDL on HPC Clusters
+=======================
 
-.. _ref_hpc_pymapdl_job:
 
-Submit a PyMAPDL job
-====================
+Introduction
+============
 
-To submit a PyMAPDL job, you must create two files:
+PyMAPDL communicates with MAPDL using the gRPC protocol.
+This protocol offers many advantages and features, for more information
+see :ref:`ref_project_page`.
+One of these features is that it is not required to have both,
+PyMAPDL and MAPDL processes, running on the same machine.
+This possibility open the door to many configurations, depending
+on whether you run them both or not on the HPC compute nodes.
+Additionally, you might to be able interact with them (``interactive`` mode)
+or not (``batch`` mode).
 
-- Python script with the PyMAPDL code
-- Bash script that activates the virtual environment and calls the Python script
+Currently, the supported configurations are:
+
+* :ref:`ref_pymapdl_batch_in_cluster_hpc`
+
+
+Since v0.68.5, PyMAPDL can take advantage of the tight integration
+between the scheduler and MAPDL to read the job configuration and
+launch an MAPDL instance that can use all the resources allocated
+to that job.
+For instance, if a SLURM job has allocated 8 nodes with 4 cores each,
+then PyMAPDL launches an MAPDL instance which uses 32 cores
+spawning across those 8 nodes.
+This behaviour can turn off if passing the environment variable
+:envvar:`PYMAPDL_ON_SLURM` or passing the argument `detect_HPC=False`
+to :func:`launch_mapdl() <ansys.mapdl.core.launcher.launch_mapdl>`.
+
+
+.. _ref_pymapdl_batch_in_cluster_hpc:
+
+Submit a PyMAPDL batch job to the cluster from the entrypoint node
+==================================================================
+
+Many HPC clusters allow their users to login in a machine using
+``ssh``, ``vnc``, ``rdp``, or similar technologies and submit a job
+to the cluster from there.
+This entrypoint machine, sometimes known as *head node* or *entrypoint node*,
+might be a virtual machine (VDI/VM).
+
+In such cases, once the Python virtual environment with PyMAPDL is already
+set and is accessible to all the compute nodes, launching a
+PyMAPDL job is very easy to do using ``sbatch`` command.
+No changes are needed on a PyMAPDL script to run it on an SLURM cluster.
+
+First the virtual environment must be activated in the current terminal.
+
+.. code-block:: console
+
+    user@entrypoint-machine:~$ export VENV_PATH=/my/path/to/the/venv
+    user@entrypoint-machine:~$ source $VENV_PATH/bin/activate
 
-**Python script:** ``pymapdl_script.py``
+Once the virtual environment has been activated, you can launch any Python
+script if they do have the proper Python shebang (``#!/usr/bin/env python3``).
+
+For instance, to launch the following Python script ``main.py``:
 
 .. code-block:: python
+    :caption: main.py
+
+    #!/usr/bin/env python3
 
     from ansys.mapdl.core import launch_mapdl
 
-    # Number of processors must be lower than the
-    # number of CPUs allocated for the job.
-    mapdl = launch_mapdl(nproc=10)
+    mapdl = launch_mapdl(run_location="/home/ubuntu/tmp/tmp/mapdl", loglevel="debug")
 
-    mapdl.prep7()
-    n_proc = mapdl.get_value("ACTIVE", 0, "NUMCPU")
-    print(f"Number of CPUs: {n_proc}")
+    print(mapdl.prep7())
+    print(f'Number of CPU: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}')
 
     mapdl.exit()
 
+You can just run in your console:
 
-**Bash script:** ``job.sh``
-
-.. code-block:: bash
+.. code-block:: console
 
-    source /home/user/.venv/bin/activate
-    python pymapdl_script.py
+    (venv) user@entrypoint-machine:~$ sbatch main.py
 
-To start the simulation, you use this code:
+Alternatively, you can remove the shebang from the python file and use a
+Python executable call:
 
 .. code-block:: console
 
-    user@machine:~$ srun job.sh
+    (venv) user@entrypoint-machine:~$ sbatch python main.py
+
+Additionally, you can change the amount of cores used in your
+job, by setting the :envvar:`PYMAPDL_NPROC` to the desired value.
 
+.. code-block:: console
+
+    (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch main.py
 
-The bash script allows you to customize the environment before running the Python script.
-This bash script performs such tasks as creating environment variables, moving to
-different directories, and printing to ensure your configuration is correct. However,
-this bash script is not mandatory.
-You can avoid having the ``job.sh`` bash script if the virtual environment is activated
-and you pass all the environment variables to the job:
+You can also add ``sbatch`` options to the command:
 
 .. code-block:: console
 
-    user@machine:~$ source /home/user/.venv/bin/activate
-    (.venv) user@machine:~$ srun python pymapdl_script.py --export=ALL
+    (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch  main.py
 
 
-The ``--export=ALL`` argument might not be needed, depending on the cluster configuration.
-Furthermore, you can omit the Python call in the preceding command if you include the
-Python shebang (``#!/usr/bin/python3``) in the first line of the ``pymapdl_script.py`` script.
+For instance, to launch a PyMAPDL job which start a four cores MAPDL instance
+on a 10 CPU SLURM job, you can use:
 
 .. code-block:: console
 
-    user@machine:~$ source /home/user/.venv/bin/activate
-    (.venv) user@machine:~$ srun pymapdl_script.py --export=ALL
+    (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py
+
+
+Using a submission script
+-------------------------
+
+In case you need to customize more your job, you can create a SLURM
+submission script to submit a PyMAPDL job.
+In this case, you must create two files:
+
+- Python script with the PyMAPDL code
+- Bash script that activates the virtual environment and calls the
+  Python script.
+
+.. code-block:: python
+    :caption: main.py
+
+    from ansys.mapdl.core import launch_mapdl
+
+    # Number of processors must be lower than the
+    # number of CPU allocated for the job.
+    mapdl = launch_mapdl(nproc=10)
+
+    mapdl.prep7()
+    n_proc = mapdl.get_value("ACTIVE", 0, "NUMCPU")
+    print(f"Number of CPU: {n_proc}")
+
+    mapdl.exit()
 
-If you prefer to run the job in the background, you can use the ``sbatch``
-command instead of the ``srun`` command. However, in this case, the Bash file is needed:
+
+.. code-block:: bash
+   :caption: job.sh
+
+   source /home/user/.venv/bin/activate
+   python main.py
+
+To start the simulation, you use this code:
 
 .. code-block:: console
 
     user@machine:~$ sbatch job.sh
-    Submitted batch job 1
 
-Here is the expected output of the job:
+In this case, the Python virtual environment does not need to be activated
+before submission since it is activated later in the script.
+
+The expected output of the job is
 
 .. code-block:: text
 
-    Number of CPUs: 10.0
+    Number of CPU: 10.0
+
 
+The bash script allows you to customize the environment before running the
+Python script.
+This bash script performs tasks such as creating environment variables,
+moving files to different directories, and printing to ensure your
+configuration is correct.

doc/source/user_guide/hpc/settings.rst

@@ -7,14 +7,16 @@ Setting PyMAPDL
 Requirements
 ============
 
-Using PyMAPDL in an HPC environment managed by SLURM scheduler has certain requirements:
+Using PyMAPDL in an HPC environment managed by SLURM scheduler has certain
+requirements:
 
 * **An Ansys installation must be accessible from all the compute nodes**.
   This normally implies that the ``ANSYS`` installation directory is in a
   shared drive or directory. Your HPC cluster administrator
   should provide you with the path to the ``ANSYS`` directory.
 
-* **A compatible Python installation must be accessible from all the compute nodes**.
+* **A compatible Python installation must be accessible from all the compute
+  nodes**.
   For compatible Python versions, see :ref:`ref_pymapdl_installation`.
 
 Additionally, you must perform a few key steps to ensure efficient job
@@ -23,8 +25,8 @@ execution and resource utilization. Subsequent topics describe these steps.
 Check the Python installation
 =============================
 
-The PyMAPDL Python package (``ansys-mapdl-core``) must be installed in a virtual
-environment that is accessible from the compute nodes.
+The PyMAPDL Python package (``ansys-mapdl-core``) must be installed in
+a virtual environment that is accessible from the compute nodes.
 
 To see where your Python distribution is installed, use this code:
 
@@ -40,9 +42,10 @@ To print the version of Python you have available, use this code:
     user@machine:~$ python3 --version
     Python 3.9.16
 
-You should be aware that your machine might have installed other Python versions.
-To find out if those installations are already in the ``PATH`` environment variable,
-you can press the **Tab** key to use autocomplete:
+You should be aware that your machine might have other Python versions
+installed.
+To find out if those installations are already in the ``PATH`` environment
+variable, you can press the **Tab** key to use autocomplete:
 
 .. code-block:: console
 
@@ -55,23 +58,34 @@ you can press the **Tab** key to use autocomplete:
 You should use a Python version that is compatible with PyMAPDL.
 For more information, see :ref:`ref_pymapdl_installation`.
 
-The ``which`` command returns the path where the Python executable is installed.
-You can use that executable to create your own Python virtual environment in a directory
-that is accessible from all the compute nodes.
-For most HPC clusters, the ``/home/$user`` directory is generally available to all nodes.
-You can then create the virtual environment in the ``/home/user/.venv`` directory:
+.. warning::
+
+    Contact your cluster administrator if you cannot find a Python version
+    compatible with PyMAPDL.
+
+
+The ``which`` command returns the path where the Python executable is
+installed.
+You can use that executable to create your own Python virtual environment
+in a directory that is accessible from all the compute nodes.
+For most HPC clusters, the ``/home/$user`` directory is generally available
+to all nodes.
+You can then create the virtual environment in the ``/home/user/.venv``
+directory:
 
 .. code-block:: console
 
     user@machine:~$ python3 -m venv /home/user/.venv
 
 After activating the virtual environment, you can install PyMAPDL.
 
+.. _ref_install_pymapdl_on_hpc:
 
 Install PyMAPDL
 ===============
 
-To install PyMAPDL on the activated virtual environment, run the following commands:
+To install PyMAPDL on the activated virtual environment, run the following
+commands:
 
 .. code-block:: console
 
@@ -107,14 +121,15 @@ then you can run that script using:
 
     user@machine:~$ srun test.sh
 
-This command might take a minute or two to complete, depending on the amount of free
-resources available in the cluster.
+This command might take a minute or two to complete, depending on the amount of
+free resources available in the cluster.
 On the console, you should see this output:
 
 .. code-block:: text
 
     Testing Python!
     PyMAPDL version 0.68.1 was successfully imported.
 
-If you see an error in the output, see :ref:`ref_hpc_troubleshooting`, especially
-:ref:`ref_python_venv_not_accesible`.
+If you see an error in the output, see :ref:`ref_hpc_troubleshooting`,
+especially :ref:`ref_python_venv_not_accesible`.
+