From ce11a7e8ea83cf0e4838e56eb0ab95439e68f64f Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Fri, 4 Oct 2024 11:40:48 +0000 Subject: [PATCH 01/35] feat: adding env vars needed for multinode --- src/ansys/mapdl/core/launcher.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 349602c667..97375fb889 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1768,6 +1768,18 @@ def launch_mapdl( f"The machine has {machine_cores} cores. PyMAPDL is asking for {nproc} cores." ) + # Setting env vars + env_vars = update_env_vars(add_env_vars, replace_env_vars) + + if ON_SLURM: + if not env_vars: + env_vars = {} + + env_vars.setdefault("ANS_CMD_NODIAG", "TRUE") + # Passing env vars for MAPDL run on multiple nodes + env_vars.setdefault("ANS_MULTIPLE_NODES", "1") + env_vars.setdefault("HYDRA_BOOTSTRAP", "slurm") + start_parm.update( { "exec_file": exec_file, From 61ad61beb942234e19ba6041c2e4d976e5ed397c Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Fri, 4 Oct 2024 11:40:48 +0000 Subject: [PATCH 02/35] feat: adding env vars needed for multinode --- src/ansys/mapdl/core/launcher.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 349602c667..97375fb889 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1768,6 +1768,18 @@ def launch_mapdl( f"The machine has {machine_cores} cores. PyMAPDL is asking for {nproc} cores." ) + # Setting env vars + env_vars = update_env_vars(add_env_vars, replace_env_vars) + + if ON_SLURM: + if not env_vars: + env_vars = {} + + env_vars.setdefault("ANS_CMD_NODIAG", "TRUE") + # Passing env vars for MAPDL run on multiple nodes + env_vars.setdefault("ANS_MULTIPLE_NODES", "1") + env_vars.setdefault("HYDRA_BOOTSTRAP", "slurm") + start_parm.update( { "exec_file": exec_file, From e9b91d4bf527818ca6fee602606d190effa520c9 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:18:55 +0000 Subject: [PATCH 03/35] feat: renaming hpc detection argument --- src/ansys/mapdl/core/launcher.py | 36 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 97375fb889..34aebe9d50 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1089,7 +1089,7 @@ def launch_mapdl( add_env_vars: Optional[Dict[str, str]] = None, replace_env_vars: Optional[Dict[str, str]] = None, version: Optional[Union[int, str]] = None, - detect_slurm_config: bool = True, + detect_HPC: bool = True, **kwargs: Dict[str, Any], ) -> Union[MapdlGrpc, "MapdlConsole"]: """Start MAPDL locally. @@ -1118,12 +1118,15 @@ def launch_mapdl( MAPDL jobname. Defaults to ``'file'``. nproc : int, optional - Number of processors. Defaults to 2. + Number of processors. Defaults to 2. If running on an HPC cluster, + this value is adjusted to the number of CPUs allocated to the job, + unless ``detect_HPC`` is set to "false". ram : float, optional - Total size in megabytes of the workspace (memory) used for the initial allocation. - The default is ``None``, in which case 2 GB (2048 MB) is used. To force a fixed size - throughout the run, specify a negative number. + Total size in megabytes of the workspace (memory) used for the initial + allocation. The default is ``None``, in which case 2 GB (2048 MB) is + used. To force a fixed size throughout the run, specify a negative + number. mode : str, optional Mode to launch MAPDL. Must be one of the following: @@ -1276,6 +1279,13 @@ def launch_mapdl( export PYMAPDL_MAPDL_VERSION=22.2 + detect_HPC: bool, optional + Whether detect if PyMAPDL is running on an HPC cluster or not. Currently + only SLURM clusters are supported. By detaul, it is set to true. + This option can be bypassed if the environment variable + ``PYMAPDL_ON_SLURM`` is set to "true". For more information visit + :ref:`ref_hpc_slurm`. + kwargs : dict, optional These keyword arguments are interface specific or for development purposes. See Notes for more details. @@ -1447,6 +1457,12 @@ def launch_mapdl( "ANSYSLMD_LICENSE_FILE":"1055@MYSERVER"} >>> mapdl = launch_mapdl(replace_env_vars=my_env_vars) """ + # Checking specific env var + if not nproc: + nproc = os.environ.get("PYMAPDL_NPROC", None) + if nproc: + nproc = int(nproc) + # By default ON_SLURM = os.environ.get("PYMAPDL_ON_SLURM", None) if ON_SLURM is None: @@ -1462,7 +1478,7 @@ def launch_mapdl( and bool(os.environ.get("SLURM_JOB_ID", "")) ) - if detect_slurm_config and ON_SLURM: + if detect_HPC and ON_SLURM: LOG.info("On Slurm mode.") # extracting parameters @@ -2134,7 +2150,7 @@ def get_value( # ntasks is for mpi SLURM_NTASKS = get_value("SLURM_NTASKS", kwargs) LOG.info(f"SLURM_NTASKS: {SLURM_NTASKS}") - # Sharing tasks acrros multiple nodes (DMP) + # Sharing tasks across multiple nodes (DMP) # the format of this envvar is a bit tricky. Avoiding it for the moment. # SLURM_TASKS_PER_NODE = int( # kwargs.pop( @@ -2178,12 +2194,6 @@ def get_value( jobname = os.environ.get("SLURM_JOB_NAME", "file") LOG.info(f"Using jobname: {jobname}") - # Checking specific env var - if not nproc: - nproc = os.environ.get("PYMAPDL_NPROC", None) - if nproc: - nproc = int(nproc) - if not nproc: ## Attempt to calculate the appropriate number of cores: # Reference: https://stackoverflow.com/a/51141287/6650211 From c714d39e6def24794d86ddd6c429430fb443fdf7 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:22:00 +0000 Subject: [PATCH 04/35] docs: adding documentation --- .../extended_examples/hpc/hpc_ml_ga.rst | 2 +- doc/source/user_guide/hpc/examples.rst | 6 + doc/source/user_guide/hpc/pymapdl.rst | 219 ++++++++---------- doc/source/user_guide/hpc/settings.rst | 135 +++++++++++ doc/source/user_guide/hpc/troubleshooting.rst | 110 +++++++-- doc/source/user_guide/index.rst | 2 + 6 files changed, 320 insertions(+), 154 deletions(-) create mode 100644 doc/source/user_guide/hpc/examples.rst create mode 100644 doc/source/user_guide/hpc/settings.rst diff --git a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst b/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst index 30570b5c6b..fb87bb7e6d 100644 --- a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst +++ b/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 ` file. diff --git a/doc/source/user_guide/hpc/examples.rst b/doc/source/user_guide/hpc/examples.rst new file mode 100644 index 0000000000..bcd96ebc8b --- /dev/null +++ b/doc/source/user_guide/hpc/examples.rst @@ -0,0 +1,6 @@ + +Examples +======== + +For an example that uses a machine learning genetic algorithm in +an HPC system managed by SLURM scheduler, see :ref:`hpc_ml_ga_example`. diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index f921e0b9d3..c70628f3a7 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -1,138 +1,130 @@ -.. _ref_hpc_pymapdl: - - -============================= -PyMAPDL on SLURM HPC clusters -============================= .. _ref_hpc_pymapdl_job: -Submit a PyMAPDL job -==================== +======================= +PyMAPDL on HPC Clusters +======================= -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. +Introduction +============ -* **A compatible Python installation must be accessible from all the compute nodes**. - For compatible Python versions, see :ref:`ref_pymapdl_installation`. +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). -Additionally, you must perform a few key steps to ensure efficient job -execution and resource utilization. Subsequent topics describe these steps. +Currently, the supported configurations are: -Check the Python installation ------------------------------ +* `Submit a PyMAPDL batch job to the cluster from the entrypoint node` -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: +Since v0.68.5, PyMAPDL can take advantage of the tigh 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 will launch an MAPDL instance which will use 32 cores +spawning across those 8 nodes. +This behaviour can disabled if passing the environment variable +:envvar:`PYMAPDL_ON_SLURM` or passing the argument `detect_HPC=False` +to :func:`launch_mapdl() `. -.. code-block:: console - user@machine:~$ which python3 - /usr/bin/python3 -To print the version of Python you have available, use this code: +Submit a PyMAPDL batch job to the cluster from the entrypoint node +================================================================== -.. code-block:: console +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). - user@machine:~$ python3 --version - Python 3.9.16 +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. -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: +First the virtual environment must be activated in the current terminal. .. code-block:: console - user@machine:~$ which python3[TAB] - python3 python3-intel64 python3.10-config python3.11 python3.12 python3.8 python3.8-intel64 python3.9-config - python3-config python3.10 python3.10-intel64 python3.11-config python3.12-config python3.8-config python3.9 - $ which python3.10 - /usr/bin/python3.10 + user@entrypoint-machine:~$ export VENV_PATH=/my/path/to/the/venv + user@entrypoint-machine:~$ source $VENV_PATH/bin/activate -You should use a Python version that is compatible with PyMAPDL. -For more information, see :ref:`ref_pymapdl_installation`. +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``). -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: +For instance, to launch the following Python script ``main.py``: -.. code-block:: console +.. code-block:: python + :caption: ``main.py`` file + + #!/usr/bin/env python3 - user@machine:~$ python3 -m venv /home/user/.venv + from ansys.mapdl.core import launch_mapdl -After activating the virtual environment, you can install PyMAPDL. + mapdl = launch_mapdl(run_location="/home/ubuntu/tmp/tmp/mapdl", loglevel="debug") + print(mapdl.prep7()) + print(f'Number of CPUs: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') -Install PyMAPDL ---------------- + mapdl.exit() -To install PyMAPDL on the activated virtual environment, run the following commands: +You can just run in your console: .. code-block:: console - user@machine:~$ source /home/user/.venv/bin/activate - (.venv) user@machine:~$ pip install ansys-mapdl-core - Collecting ansys-mapdl-core - Downloading ansys_mapdl_core-0.68.1-py3-none-any.whl (26.9 MB) - ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 26.9/26.9 MB 37.3 MB/s eta 0:00:00 - Collecting pexpect>=4.8.0 - Using cached pexpect-4.9.0-py2.py3-none-any.whl (63 kB) - Collecting click>=8.1.3 - ... + (venv) user@entrypoint-machine:~$ sbatch main.py -To test if this virtual environment is accessible from the compute nodes, -run this ``test.sh`` bash script: +Alternatively, you can remove the shebang from the python file and use a +Python executable call: -.. code-block:: bash +.. code-block:: console + + (venv) user@entrypoint-machine:~$ sbatch python main.py - #!/bin/bash - #SBATCH --job-name=myjob - #SBATCH --nodes=1 - #SBATCH --ntasks-per-node=4 - #SBATCH --time=01:00:00 +Additionally, you can can change the amount of cores used in your +job, by setting the :envvar:`PYMAPDL_NPROC` to the desired value. + +.. code-block:: console - # Commands to run - echo "Testing Python!" - source /home/user/.venv/bin/activate - python -c "from ansys.mapdl import core;print(f'PyMAPDL version {core.__version__} was successfully imported.')" + (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch main.py -then you can run that script using: +You can also add ``sbatch`` options to the command: .. code-block:: console - user@machine:~$ srun test.sh + (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch main.py -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 +For instance, to launch a PyMAPDL job which start a four cores MAPDL instance +on a 10 CPUs SLURM job, you can use: + +.. code-block:: bash - Testing Python! - PyMAPDL version 0.68.1 was successfully imported. + (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py -If you see an error in the output, see :ref:`ref_hpc_troubleshooting`, especially -:ref:`ref_python_venv_not_accesible`. -Submit a PyMAPDL job --------------------- +Using a submission script +------------------------- -To submit a PyMAPDL job, you must create two files: +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 - -**Python script:** ``pymapdl_script.py`` +- Bash script that activates the virtual environment and calls the + Python script. .. code-block:: python + :caption: ``main.py`` python script from ansys.mapdl.core import launch_mapdl @@ -147,59 +139,30 @@ To submit a PyMAPDL job, you must create two files: mapdl.exit() -**Bash script:** ``job.sh`` - .. code-block:: bash + :caption: ``job.sh`` execution script - source /home/user/.venv/bin/activate - python pymapdl_script.py + source /home/user/.venv/bin/activate + python main.py To start the simulation, you use this code: -.. code-block:: console - - user@machine:~$ srun job.sh - - -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: - -.. code-block:: console - - user@machine:~$ source /home/user/.venv/bin/activate - (.venv) user@machine:~$ srun python pymapdl_script.py --export=ALL - - -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. - -.. code-block:: console - - user@machine:~$ source /home/user/.venv/bin/activate - (.venv) user@machine:~$ srun pymapdl_script.py --export=ALL - -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:: 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 -Examples -======== - -For an example that uses a machine learning genetic algorithm in -an HPC system managed by SLURM scheduler, see :ref:`hpc_ml_ga_example`. +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. diff --git a/doc/source/user_guide/hpc/settings.rst b/doc/source/user_guide/hpc/settings.rst new file mode 100644 index 0000000000..f4366ab6f0 --- /dev/null +++ b/doc/source/user_guide/hpc/settings.rst @@ -0,0 +1,135 @@ +.. _ref_setting_pymapdl_on_hpc: + +=============== +Setting PyMAPDL +=============== + +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**. + For compatible Python versions, see :ref:`ref_pymapdl_installation`. + +Additionally, you must perform a few key steps to ensure efficient job +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. + +To see where your Python distribution is installed, use this code: + +.. code-block:: console + + user@machine:~$ which python3 + /usr/bin/python3 + +To print the version of Python you have available, use this code: + +.. code-block:: console + + user@machine:~$ python3 --version + Python 3.9.16 + +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 + + user@machine:~$ which python3[TAB] + python3 python3-intel64 python3.10-config python3.11 python3.12 python3.8 python3.8-intel64 python3.9-config + python3-config python3.10 python3.10-intel64 python3.11-config python3.12-config python3.8-config python3.9 + $ which python3.10 + /usr/bin/python3.10 + +You should use a Python version that is compatible with PyMAPDL. +For more information, see :ref:`ref_pymapdl_installation`. + +.. 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: + +.. code-block:: console + + user@machine:~$ source /home/user/.venv/bin/activate + (.venv) user@machine:~$ pip install ansys-mapdl-core + Collecting ansys-mapdl-core + Downloading ansys_mapdl_core-0.68.1-py3-none-any.whl (26.9 MB) + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 26.9/26.9 MB 37.3 MB/s eta 0:00:00 + Collecting pexpect>=4.8.0 + Using cached pexpect-4.9.0-py2.py3-none-any.whl (63 kB) + Collecting click>=8.1.3 + ... + +To test if this virtual environment is accessible from the compute nodes, +run this ``test.sh`` bash script: + +.. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=myjob + #SBATCH --nodes=1 + #SBATCH --ntasks-per-node=4 + #SBATCH --time=01:00:00 + + # Commands to run + echo "Testing Python!" + source /home/user/.venv/bin/activate + python -c "from ansys.mapdl import core;print(f'PyMAPDL version {core.__version__} was successfully imported.')" + +then you can run that script using: + +.. code-block:: console + + 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. +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`. + diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 3a41a60537..8f84a202df 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -7,8 +7,19 @@ Troubleshooting Debugging jobs -------------- -- Use ``--output`` and ``--error`` directives in batch scripts to capture - standard output and error messages. +- Use ``--output`` and ``--error`` directives in batch scripts to captures + standard output and error messages to specific files. + + .. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --output=ansys_job.out # Standard output file + #SBATCH --error=ansys_job.err # Standard error file + + source /home/user/pymapdl/.venv/bin/activate + python /home/user/pymapdl.py - Check SLURM logs for error messages and debugging information. @@ -19,44 +30,90 @@ Python virtual environment is not accessible -------------------------------------------- If there is an error while testing the Python installation, it might mean that the Python environment is not accessible to the compute nodes. -For example, in the following output, PyMAPDL could not be found, meaning that the script -is not using the virtual environment (``/home/user/.venv``): +For example, given the following *bash* script `test.sh`: + +.. code-block:: bash + + source /home/user/.venv/bin/activate + python -c "from ansys.mapdl import core as pymapdl; pymapdl.report()" + +The following output is shown after running in the terminal: .. code-block:: console user@machine:~$ srun test.sh + Testing Python! Traceback (most recent call last): File "", line 1, in ImportError: No module named ansys.mapdl -This could be for a number of reasons. One of them is that the system Python distribution -used to create the virtual environment is not accessible from the compute nodes +As the output shows, PyMAPDL could not be found, meaning that either: +* The virtual environment does not have PyMAPDL installed. + See :ref:`ref_install_pymapdl_on_hpc`. +* Or the script did not activate properly the virtual environment + (``/home/user/.venv``). + +For the second reason, there could be a number of reasons. +One of them is that the system Python distribution used to create +the virtual environment is not accessible from the compute nodes due to one of these reasons: - The virtual environment has been created in a directory that is not accessible from the nodes. -- The virtual environment has been created from a Python - executable that is not available to the compute nodes. - Hence, the virtual environment is not activated. For - example, you might be creating the virtual environment - using Python 3.10, but only Python 3.8 is available - from the compute nodes. - -You can test which Python executable the cluster is using by starting an interactive session in -a compute node with this code: + In this case, your terminal might also show that the + ``activate`` file could not be found. + + .. code-block:: console + + user@machine:~$ srun test.sh + Testing Python! + bash: .venv/bin/activate: No such file or directory + + Depending on your terminal configuration, the above error might be sufficient + to exit the terminal process, or not. + If not, the execution will continue, and the subsequent ``python`` call will + be executed using the default python executable. + It is very likely that the default ``python`` executable does not have + PyMAPDL installed, hence the ``ImportError`` error showed above might appear + too. + +- The virtual environment has been created from a Python executable that is + not available to the compute nodes. Hence, the virtual environment is not + activated. + For example, you might be creating the virtual environment Using + Python 3.10, but only Python 3.8 is available from the compute nodes. + You can test which Python executable the cluster is using by starting an + interactive session in a compute node with this code to list all commands + which starts with ``python``: .. code-block:: console user@machine:~$ srun --pty /bin/bash - user@compute_node_01:~$ compgen -c | grep python # List all commands starting with python + user@compute_node_01:~$ compgen -c | grep python .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch +It should be noticed the above approach assumes that all the nodes have similar +configuration, hence all of them should have the same Python installations +available. + +It is also convenient to be aware that environment variable modules can be +used to activate Python installations. +For more information, see :ref:`ref_envvar_modules_on_hpc`. + + +.. _ref_envvar_modules_on_hpc: + +Using modules to load Python +---------------------------- + Many HPC infrastructures use environment managers to load and unload -software packages using modules and environment variables. -Hence, you might want to make sure that the correct module is loaded in your script. +software packages using modules and environment variables. +Hence, you might want to make sure that the correct module is loaded in your +script. + For information on two of the most common environment managers, see the `Modules documentation `_ and `Lmod documentation `_. Check your cluster documentation to know which environment @@ -76,12 +133,14 @@ Using the Ansys-provided Python installation **For development purposes only** -In certain HPC environments the possibility of installing a different Python version -is limited for security reasons. In such cases, the Python distribution available in -the Ansys installation can be used. -This Python distribution is a customized Python (CPython) -version for Ansys products use only. Its use is **discouraged** -except for very advanced users and special use cases. +In certain HPC environments the possibility of installing a different Python +version is limited for security reasons. +In such cases, the Python distribution available in the Ansys installation +can be used. +This Python distribution is a customized Python (CPython) version for Ansys +products use only. +Its use is **discouraged** except for very advanced users and special use +cases. This Python distribution is in the following directory, where ``%MAPDL_VERSION%`` is the three-digit Ansys version: @@ -98,7 +157,8 @@ For example, here is the directory for Ansys 2024 R2: In Ansys 2024 R1 and later, the unified installer includes CPython 3.10. -Earlier versions include CPython 3.7 (``/commonfiles/CPython/3_7/linx64/Release/python``). +Earlier versions include CPython 3.7 +(``/commonfiles/CPython/3_7/linx64/Release/python``). Because the Ansys installation must be available to all the compute nodes to run simulations using them, this diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index ef12344826..c750478f74 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -51,7 +51,9 @@ This section provides a general overview of PyMAPDL and how you use it. :caption: High performance computing hpc/introduction + hpc/settings hpc/pymapdl + hpc/examples hpc/troubleshooting From 492345ba5ebf1872b3abad301ab7b4169f2dfddb Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:34:40 +0000 Subject: [PATCH 05/35] chore: adding changelog file 3466.documentation.md --- doc/changelog.d/3466.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/3466.documentation.md diff --git a/doc/changelog.d/3466.documentation.md b/doc/changelog.d/3466.documentation.md new file mode 100644 index 0000000000..902767602d --- /dev/null +++ b/doc/changelog.d/3466.documentation.md @@ -0,0 +1 @@ +feat: passing tight integration env vars to mapdl \ No newline at end of file From a289dabaaab87bed43b802400d8e2c27c2efea92 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Fri, 4 Oct 2024 11:40:48 +0000 Subject: [PATCH 06/35] feat: adding env vars needed for multinode --- src/ansys/mapdl/core/launcher.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 349602c667..97375fb889 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1768,6 +1768,18 @@ def launch_mapdl( f"The machine has {machine_cores} cores. PyMAPDL is asking for {nproc} cores." ) + # Setting env vars + env_vars = update_env_vars(add_env_vars, replace_env_vars) + + if ON_SLURM: + if not env_vars: + env_vars = {} + + env_vars.setdefault("ANS_CMD_NODIAG", "TRUE") + # Passing env vars for MAPDL run on multiple nodes + env_vars.setdefault("ANS_MULTIPLE_NODES", "1") + env_vars.setdefault("HYDRA_BOOTSTRAP", "slurm") + start_parm.update( { "exec_file": exec_file, From 604bbf8dd0ba21731e08b5ea757757808b2aa945 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:18:55 +0000 Subject: [PATCH 07/35] feat: renaming hpc detection argument --- src/ansys/mapdl/core/launcher.py | 36 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 97375fb889..34aebe9d50 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1089,7 +1089,7 @@ def launch_mapdl( add_env_vars: Optional[Dict[str, str]] = None, replace_env_vars: Optional[Dict[str, str]] = None, version: Optional[Union[int, str]] = None, - detect_slurm_config: bool = True, + detect_HPC: bool = True, **kwargs: Dict[str, Any], ) -> Union[MapdlGrpc, "MapdlConsole"]: """Start MAPDL locally. @@ -1118,12 +1118,15 @@ def launch_mapdl( MAPDL jobname. Defaults to ``'file'``. nproc : int, optional - Number of processors. Defaults to 2. + Number of processors. Defaults to 2. If running on an HPC cluster, + this value is adjusted to the number of CPUs allocated to the job, + unless ``detect_HPC`` is set to "false". ram : float, optional - Total size in megabytes of the workspace (memory) used for the initial allocation. - The default is ``None``, in which case 2 GB (2048 MB) is used. To force a fixed size - throughout the run, specify a negative number. + Total size in megabytes of the workspace (memory) used for the initial + allocation. The default is ``None``, in which case 2 GB (2048 MB) is + used. To force a fixed size throughout the run, specify a negative + number. mode : str, optional Mode to launch MAPDL. Must be one of the following: @@ -1276,6 +1279,13 @@ def launch_mapdl( export PYMAPDL_MAPDL_VERSION=22.2 + detect_HPC: bool, optional + Whether detect if PyMAPDL is running on an HPC cluster or not. Currently + only SLURM clusters are supported. By detaul, it is set to true. + This option can be bypassed if the environment variable + ``PYMAPDL_ON_SLURM`` is set to "true". For more information visit + :ref:`ref_hpc_slurm`. + kwargs : dict, optional These keyword arguments are interface specific or for development purposes. See Notes for more details. @@ -1447,6 +1457,12 @@ def launch_mapdl( "ANSYSLMD_LICENSE_FILE":"1055@MYSERVER"} >>> mapdl = launch_mapdl(replace_env_vars=my_env_vars) """ + # Checking specific env var + if not nproc: + nproc = os.environ.get("PYMAPDL_NPROC", None) + if nproc: + nproc = int(nproc) + # By default ON_SLURM = os.environ.get("PYMAPDL_ON_SLURM", None) if ON_SLURM is None: @@ -1462,7 +1478,7 @@ def launch_mapdl( and bool(os.environ.get("SLURM_JOB_ID", "")) ) - if detect_slurm_config and ON_SLURM: + if detect_HPC and ON_SLURM: LOG.info("On Slurm mode.") # extracting parameters @@ -2134,7 +2150,7 @@ def get_value( # ntasks is for mpi SLURM_NTASKS = get_value("SLURM_NTASKS", kwargs) LOG.info(f"SLURM_NTASKS: {SLURM_NTASKS}") - # Sharing tasks acrros multiple nodes (DMP) + # Sharing tasks across multiple nodes (DMP) # the format of this envvar is a bit tricky. Avoiding it for the moment. # SLURM_TASKS_PER_NODE = int( # kwargs.pop( @@ -2178,12 +2194,6 @@ def get_value( jobname = os.environ.get("SLURM_JOB_NAME", "file") LOG.info(f"Using jobname: {jobname}") - # Checking specific env var - if not nproc: - nproc = os.environ.get("PYMAPDL_NPROC", None) - if nproc: - nproc = int(nproc) - if not nproc: ## Attempt to calculate the appropriate number of cores: # Reference: https://stackoverflow.com/a/51141287/6650211 From 1d296519e1758af6c09da85ff9ff5ecc3573a01b Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:22:00 +0000 Subject: [PATCH 08/35] docs: adding documentation --- .../extended_examples/hpc/hpc_ml_ga.rst | 2 +- doc/source/user_guide/hpc/pymapdl.rst | 168 +++++++++++++----- doc/source/user_guide/hpc/settings.rst | 49 +++-- doc/source/user_guide/hpc/troubleshooting.rst | 110 +++++++++--- 4 files changed, 244 insertions(+), 85 deletions(-) diff --git a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst b/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst index 30570b5c6b..fb87bb7e6d 100644 --- a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst +++ b/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 ` file. diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index e0fddefa78..c70628f3a7 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -1,84 +1,168 @@ -.. _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: + +* `Submit a PyMAPDL batch job to the cluster from the entrypoint node` + + +Since v0.68.5, PyMAPDL can take advantage of the tigh 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 will launch an MAPDL instance which will use 32 cores +spawning across those 8 nodes. +This behaviour can disabled if passing the environment variable +:envvar:`PYMAPDL_ON_SLURM` or passing the argument `detect_HPC=False` +to :func:`launch_mapdl() `. + + + +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`` file + + #!/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 CPUs: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') mapdl.exit() +You can just run in your console: -**Bash script:** ``job.sh`` +.. code-block:: console -.. code-block:: bash + (venv) user@entrypoint-machine:~$ sbatch main.py - source /home/user/.venv/bin/activate - python pymapdl_script.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 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 CPUs SLURM job, you can use: -.. code-block:: console +.. code-block:: bash + + (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py - user@machine:~$ source /home/user/.venv/bin/activate - (.venv) user@machine:~$ srun pymapdl_script.py --export=ALL -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: +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`` python script + + 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.prep7() + n_proc = mapdl.get_value("ACTIVE", 0, "NUMCPU") + print(f"Number of CPUs: {n_proc}") + + mapdl.exit() + + +.. code-block:: bash + :caption: ``job.sh`` execution script + + 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 + +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. diff --git a/doc/source/user_guide/hpc/settings.rst b/doc/source/user_guide/hpc/settings.rst index 7f6af61c63..f4366ab6f0 100644 --- a/doc/source/user_guide/hpc/settings.rst +++ b/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,11 +58,20 @@ 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 @@ -67,11 +79,13 @@ You can then create the virtual environment in the ``/home/user/.venv`` director 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,8 +121,8 @@ 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 @@ -116,5 +130,6 @@ On the console, you should see this output: 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`. + diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 3a41a60537..8f84a202df 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -7,8 +7,19 @@ Troubleshooting Debugging jobs -------------- -- Use ``--output`` and ``--error`` directives in batch scripts to capture - standard output and error messages. +- Use ``--output`` and ``--error`` directives in batch scripts to captures + standard output and error messages to specific files. + + .. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --output=ansys_job.out # Standard output file + #SBATCH --error=ansys_job.err # Standard error file + + source /home/user/pymapdl/.venv/bin/activate + python /home/user/pymapdl.py - Check SLURM logs for error messages and debugging information. @@ -19,44 +30,90 @@ Python virtual environment is not accessible -------------------------------------------- If there is an error while testing the Python installation, it might mean that the Python environment is not accessible to the compute nodes. -For example, in the following output, PyMAPDL could not be found, meaning that the script -is not using the virtual environment (``/home/user/.venv``): +For example, given the following *bash* script `test.sh`: + +.. code-block:: bash + + source /home/user/.venv/bin/activate + python -c "from ansys.mapdl import core as pymapdl; pymapdl.report()" + +The following output is shown after running in the terminal: .. code-block:: console user@machine:~$ srun test.sh + Testing Python! Traceback (most recent call last): File "", line 1, in ImportError: No module named ansys.mapdl -This could be for a number of reasons. One of them is that the system Python distribution -used to create the virtual environment is not accessible from the compute nodes +As the output shows, PyMAPDL could not be found, meaning that either: +* The virtual environment does not have PyMAPDL installed. + See :ref:`ref_install_pymapdl_on_hpc`. +* Or the script did not activate properly the virtual environment + (``/home/user/.venv``). + +For the second reason, there could be a number of reasons. +One of them is that the system Python distribution used to create +the virtual environment is not accessible from the compute nodes due to one of these reasons: - The virtual environment has been created in a directory that is not accessible from the nodes. -- The virtual environment has been created from a Python - executable that is not available to the compute nodes. - Hence, the virtual environment is not activated. For - example, you might be creating the virtual environment - using Python 3.10, but only Python 3.8 is available - from the compute nodes. - -You can test which Python executable the cluster is using by starting an interactive session in -a compute node with this code: + In this case, your terminal might also show that the + ``activate`` file could not be found. + + .. code-block:: console + + user@machine:~$ srun test.sh + Testing Python! + bash: .venv/bin/activate: No such file or directory + + Depending on your terminal configuration, the above error might be sufficient + to exit the terminal process, or not. + If not, the execution will continue, and the subsequent ``python`` call will + be executed using the default python executable. + It is very likely that the default ``python`` executable does not have + PyMAPDL installed, hence the ``ImportError`` error showed above might appear + too. + +- The virtual environment has been created from a Python executable that is + not available to the compute nodes. Hence, the virtual environment is not + activated. + For example, you might be creating the virtual environment Using + Python 3.10, but only Python 3.8 is available from the compute nodes. + You can test which Python executable the cluster is using by starting an + interactive session in a compute node with this code to list all commands + which starts with ``python``: .. code-block:: console user@machine:~$ srun --pty /bin/bash - user@compute_node_01:~$ compgen -c | grep python # List all commands starting with python + user@compute_node_01:~$ compgen -c | grep python .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch +It should be noticed the above approach assumes that all the nodes have similar +configuration, hence all of them should have the same Python installations +available. + +It is also convenient to be aware that environment variable modules can be +used to activate Python installations. +For more information, see :ref:`ref_envvar_modules_on_hpc`. + + +.. _ref_envvar_modules_on_hpc: + +Using modules to load Python +---------------------------- + Many HPC infrastructures use environment managers to load and unload -software packages using modules and environment variables. -Hence, you might want to make sure that the correct module is loaded in your script. +software packages using modules and environment variables. +Hence, you might want to make sure that the correct module is loaded in your +script. + For information on two of the most common environment managers, see the `Modules documentation `_ and `Lmod documentation `_. Check your cluster documentation to know which environment @@ -76,12 +133,14 @@ Using the Ansys-provided Python installation **For development purposes only** -In certain HPC environments the possibility of installing a different Python version -is limited for security reasons. In such cases, the Python distribution available in -the Ansys installation can be used. -This Python distribution is a customized Python (CPython) -version for Ansys products use only. Its use is **discouraged** -except for very advanced users and special use cases. +In certain HPC environments the possibility of installing a different Python +version is limited for security reasons. +In such cases, the Python distribution available in the Ansys installation +can be used. +This Python distribution is a customized Python (CPython) version for Ansys +products use only. +Its use is **discouraged** except for very advanced users and special use +cases. This Python distribution is in the following directory, where ``%MAPDL_VERSION%`` is the three-digit Ansys version: @@ -98,7 +157,8 @@ For example, here is the directory for Ansys 2024 R2: In Ansys 2024 R1 and later, the unified installer includes CPython 3.10. -Earlier versions include CPython 3.7 (``/commonfiles/CPython/3_7/linx64/Release/python``). +Earlier versions include CPython 3.7 +(``/commonfiles/CPython/3_7/linx64/Release/python``). Because the Ansys installation must be available to all the compute nodes to run simulations using them, this From 96929a8f6302bfb855bbae492fa2e463cf923321 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:34:40 +0000 Subject: [PATCH 09/35] chore: adding changelog file 3466.documentation.md --- doc/changelog.d/3466.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/3466.documentation.md diff --git a/doc/changelog.d/3466.documentation.md b/doc/changelog.d/3466.documentation.md new file mode 100644 index 0000000000..902767602d --- /dev/null +++ b/doc/changelog.d/3466.documentation.md @@ -0,0 +1 @@ +feat: passing tight integration env vars to mapdl \ No newline at end of file From 6ab1d65bc376ae823e79a39cbe043f74f10446f9 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 12:36:55 +0000 Subject: [PATCH 10/35] fix: vale issues --- doc/source/user_guide/hpc/pymapdl.rst | 16 ++++++++-------- doc/source/user_guide/hpc/troubleshooting.rst | 14 +++++++------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index c70628f3a7..f24134509f 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -29,9 +29,9 @@ 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 will launch an MAPDL instance which will use 32 cores +then PyMAPDL launches an MAPDL instance which uses 32 cores spawning across those 8 nodes. -This behaviour can disabled if passing the environment variable +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() `. @@ -73,7 +73,7 @@ For instance, to launch the following Python script ``main.py``: mapdl = launch_mapdl(run_location="/home/ubuntu/tmp/tmp/mapdl", loglevel="debug") print(mapdl.prep7()) - print(f'Number of CPUs: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') + print(f'Number of CPU: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') mapdl.exit() @@ -90,7 +90,7 @@ Python executable call: (venv) user@entrypoint-machine:~$ sbatch python main.py -Additionally, you can can change the amount of cores used in your +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 @@ -105,7 +105,7 @@ You can also add ``sbatch`` options to the command: For instance, to launch a PyMAPDL job which start a four cores MAPDL instance -on a 10 CPUs SLURM job, you can use: +on a 10 CPU SLURM job, you can use: .. code-block:: bash @@ -129,12 +129,12 @@ In this case, you must create two files: from ansys.mapdl.core import launch_mapdl # Number of processors must be lower than the - # number of CPUs allocated for the job. + # 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 CPUs: {n_proc}") + print(f"Number of CPU: {n_proc}") mapdl.exit() @@ -158,7 +158,7 @@ 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 diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 8f84a202df..9e79d0fc8b 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -70,13 +70,13 @@ due to one of these reasons: Testing Python! bash: .venv/bin/activate: No such file or directory - Depending on your terminal configuration, the above error might be sufficient - to exit the terminal process, or not. - If not, the execution will continue, and the subsequent ``python`` call will - be executed using the default python executable. + Depending on your terminal configuration, the preceding error might be + sufficient to exit the terminal process, or not. + If not, the execution continues, and the subsequent ``python`` call is + executed using the default python executable. It is very likely that the default ``python`` executable does not have - PyMAPDL installed, hence the ``ImportError`` error showed above might appear - too. + PyMAPDL installed, hence the ``ImportError`` error showed preceding might + appear too. - The virtual environment has been created from a Python executable that is not available to the compute nodes. Hence, the virtual environment is not @@ -95,7 +95,7 @@ due to one of these reasons: .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch -It should be noticed the above approach assumes that all the nodes have similar +It should be noticed the preceding approach assumes that all the nodes have similar configuration, hence all of them should have the same Python installations available. From e45d2e5d4fb97359605f445f462fa4b9cf76515a Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 15:35:36 +0200 Subject: [PATCH 11/35] chore: To fix sphinx build Squashed commit of the following: commit c1d1a3ea278e6461bcc91e1c965f6e6a46d00bc3 Author: German <28149841+germa89@users.noreply.github.com> Date: Mon Oct 7 15:33:19 2024 +0200 ci: retrigger CICD commit b7b5c30a422413d203a31f5a29b7e57f93a0ab08 Author: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon Oct 7 13:31:55 2024 +0000 ci: auto fixes from pre-commit.com hooks. for more information, see https://pre-commit.ci commit 32a1c0203fc5101f429aafafba26a28cc06bf24c Author: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> Date: Mon Oct 7 15:31:24 2024 +0200 fix: add suggestions Co-authored-by: German <28149841+germa89@users.noreply.github.com> commit 575a219ef8b135b234f2ec5f24a9585298845eca Merge: f2afe139f be1be2e2c Author: Revathyvenugopal162 Date: Mon Oct 7 15:09:01 2024 +0200 Merge branch 'fix/add-build-cheatsheet-as-env-varaible' of https://github.com/ansys/pymapdl into fix/add-build-cheatsheet-as-env-varaible commit f2afe139f693f4f1979506662c514692280487a9 Author: Revathyvenugopal162 Date: Mon Oct 7 15:08:58 2024 +0200 fix: precommit commit be1be2e2ca4f8736db0b180ab3d8cc6bff696412 Author: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon Oct 7 13:07:35 2024 +0000 chore: adding changelog file 3468.fixed.md commit f052a4dba77cb586be59232d2627d7814077f094 Author: Revathyvenugopal162 Date: Mon Oct 7 15:05:56 2024 +0200 fix: add build cheatsheet as env variable within doc-build --- .github/workflows/ci.yml | 1 + doc/changelog.d/3468.fixed.md | 1 + doc/source/conf.py | 10 +++++++--- 3 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 doc/changelog.d/3468.fixed.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 30f1396175..543cc91b08 100644 --- a/.github/workflows/ci.yml +++ b/.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%-... diff --git a/doc/changelog.d/3468.fixed.md b/doc/changelog.d/3468.fixed.md new file mode 100644 index 0000000000..ab369c1e41 --- /dev/null +++ b/doc/changelog.d/3468.fixed.md @@ -0,0 +1 @@ +fix: add ``build cheatsheet`` as env variable within doc-build \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index f874f6f4c7..90bcebb79d 100755 --- a/doc/source/conf.py +++ b/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 From bb2b90afbbb07fbd86069618d27f3276c32db726 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 15:56:36 +0200 Subject: [PATCH 12/35] docs: expanding a bit troubleshooting advices and small format fix --- doc/source/user_guide/hpc/pymapdl.rst | 11 ++++--- doc/source/user_guide/hpc/troubleshooting.rst | 31 ++++++++++++++++--- doc/source/user_guide/troubleshoot.rst | 1 + 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index f24134509f..070cfdcda0 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -21,7 +21,7 @@ or not (``batch`` mode). Currently, the supported configurations are: -* `Submit a PyMAPDL batch job to the cluster from the entrypoint node` +* :ref:`ref_pymapdl_batch_in_cluster_hpc` Since v0.68.5, PyMAPDL can take advantage of the tigh integration @@ -36,6 +36,7 @@ This behaviour can turn off if passing the environment variable to :func:`launch_mapdl() `. +.. _ref_pymapdl_batch_in_cluster_hpc: Submit a PyMAPDL batch job to the cluster from the entrypoint node ================================================================== @@ -64,7 +65,7 @@ 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`` file + :caption: main.py #!/usr/bin/env python3 @@ -107,7 +108,7 @@ You can also add ``sbatch`` options to the command: 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:: bash +.. code-block:: console (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py @@ -124,7 +125,7 @@ In this case, you must create two files: Python script. .. code-block:: python - :caption: ``main.py`` python script + :caption: main.py from ansys.mapdl.core import launch_mapdl @@ -140,7 +141,7 @@ In this case, you must create two files: .. code-block:: bash - :caption: ``job.sh`` execution script + :caption: job.sh source /home/user/.venv/bin/activate python main.py diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 9e79d0fc8b..528c00fea9 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -22,6 +22,26 @@ Debugging jobs python /home/user/pymapdl.py - Check SLURM logs for error messages and debugging information. +- It is also good idea to print the environment variables in your bash script, using + ``printenv``. Additionally, you can filter them using ``grep``. + + .. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --output=ansys_job.out # Standard output file + #SBATCH --error=ansys_job.err # Standard error file + + printenv | grep "PYMAPDL" # Print env vars which contains 'PYMAPDL' + printenv | grep "SLURM" # Print env vars which contains 'SLURM' + source /home/user/pymapdl/.venv/bin/activate + python /home/user/pymapdl.py + +- Use PyMAPDL logging to printout valuable information. To activate this, see + :ref:`ref_debug_pymapdl`. + +- In case you need more help, visit :ref:`ref_troubleshooting`. .. _ref_python_venv_not_accesible: @@ -49,8 +69,10 @@ The following output is shown after running in the terminal: ImportError: No module named ansys.mapdl As the output shows, PyMAPDL could not be found, meaning that either: + * The virtual environment does not have PyMAPDL installed. See :ref:`ref_install_pymapdl_on_hpc`. + * Or the script did not activate properly the virtual environment (``/home/user/.venv``). @@ -59,10 +81,9 @@ One of them is that the system Python distribution used to create the virtual environment is not accessible from the compute nodes due to one of these reasons: -- The virtual environment has been created in a - directory that is not accessible from the nodes. - In this case, your terminal might also show that the - ``activate`` file could not be found. +- The virtual environment has been created in a directory that is + not accessible from the nodes. In this case, your terminal might + also show that the ``activate`` file could not be found. .. code-block:: console @@ -176,6 +197,8 @@ the compute nodes: user@machine:~$ export PY_PATH=/ansys_inc/v241/commonfiles/CPython/3_10/linx64/Release/Python + This path needs to be adapted to where Ansys is installed and also which version is used. + #. For only Ansys 2024 R1 and earlier, patch the ``PATH`` and ``LD_LIBRARY_PATH`` environment variables: diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 54cf12d0c7..74a2b63f35 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -8,6 +8,7 @@ Troubleshooting PyMAPDL To help you resolve any problems that you might have when using PyMAPDL, some of the most common problems and frequently asked questions are posted here. +.. _ref_debug_pymapdl: Debug in PyMAPDL ---------------- From 330f33c30a966eeda24aed4bd5caabb30d97511e Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 14:03:57 +0000 Subject: [PATCH 13/35] docs: fix vale --- doc/source/user_guide/hpc/pymapdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index f24134509f..5a3faa9962 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -24,7 +24,7 @@ Currently, the supported configurations are: * `Submit a PyMAPDL batch job to the cluster from the entrypoint node` -Since v0.68.5, PyMAPDL can take advantage of the tigh integration +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. From ac54f2c987817093698f5cd3d0c101e637038d29 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 16:42:24 +0200 Subject: [PATCH 14/35] fix: nproc tests --- src/ansys/mapdl/core/launcher.py | 1 + tests/test_launcher.py | 23 +++++++++++++++++------ 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 34aebe9d50..18fa51c27e 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -2295,4 +2295,5 @@ def pack_parameters(locals_var): dict_["start_instance"] = locals_var["start_instance"] dict_["version"] = locals_var["version"] dict_["additional_switches"] = locals_var["additional_switches"] + dict_["nproc"] = locals_var["nproc"] return dict_ diff --git a/tests/test_launcher.py b/tests/test_launcher.py index 5be0570c31..1b66a59863 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -604,7 +604,6 @@ def test_deprecate_verbose(): ), pytest.param( { - "PYMAPDL_NPROC": 5, "SLURM_JOB_NAME": "myawesomejob", "SLURM_NTASKS": 2, "SLURM_CPUS_PER_TASK": 2, @@ -613,12 +612,11 @@ def test_deprecate_verbose(): "SLURM_MEM_PER_NODE": None, "SLURM_NODELIST": None, }, - {"nproc": 5, "jobname": "myawesomejob"}, - id="Testing PYMAPDL_NPROC and SLURM_JOB_NAME", + {"nproc": 4, "jobname": "myawesomejob"}, + id="Testing SLURM_JOB_NAME", ), pytest.param( { - "PYMAPDL_NPROC": 5, "SLURM_JOB_NAME": "myawesomejob", "SLURM_NTASKS": 2, "SLURM_CPUS_PER_TASK": 2, @@ -628,8 +626,8 @@ def test_deprecate_verbose(): "SLURM_NODELIST": None, "PYMAPDL_MAPDL_EXEC": "asdf/qwer/poiu", }, - {"nproc": 5, "jobname": "myawesomejob", "exec_file": "asdf/qwer/poiu"}, - id="Testing PYMAPDL_NPROC and SLURM_JOB_NAME", + {"nproc": 4, "jobname": "myawesomejob", "exec_file": "asdf/qwer/poiu"}, + id="Testing PYMAPDL_MAPDL_EXEC and SLURM_JOB_NAME", ), ), indirect=["set_env_var_context"], @@ -782,3 +780,16 @@ def test_ip_and_start_instance( assert options["ip"] == ip else: assert options["ip"] in (LOCALHOST, "0.0.0.0") + + +def test_nproc_envvar(monkeypatch): + monkeypatch.setenv("PYMAPDL_NPROC", 10) + args = launch_mapdl(_debug_no_launch=True) + assert args["nproc"] == 10 + + +@pytest.mark.parametrize("nproc,result", [[None, 2], [5, 5]]) +def test_nproc(monkeypatch, nproc, result): + monkeypatch.delenv("PYMAPDL_START_INSTANCE") + args = launch_mapdl(nproc=nproc, _debug_no_launch=True) + assert args["nproc"] == result From 6985ee4adbc37528adea01bc1bfab48234172c33 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Fri, 4 Oct 2024 11:40:48 +0000 Subject: [PATCH 15/35] feat: adding env vars needed for multinode --- src/ansys/mapdl/core/launcher.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 349602c667..97375fb889 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1768,6 +1768,18 @@ def launch_mapdl( f"The machine has {machine_cores} cores. PyMAPDL is asking for {nproc} cores." ) + # Setting env vars + env_vars = update_env_vars(add_env_vars, replace_env_vars) + + if ON_SLURM: + if not env_vars: + env_vars = {} + + env_vars.setdefault("ANS_CMD_NODIAG", "TRUE") + # Passing env vars for MAPDL run on multiple nodes + env_vars.setdefault("ANS_MULTIPLE_NODES", "1") + env_vars.setdefault("HYDRA_BOOTSTRAP", "slurm") + start_parm.update( { "exec_file": exec_file, From 03a05e61b821b91a29f12f2c053524e13fe2347f Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:18:55 +0000 Subject: [PATCH 16/35] feat: renaming hpc detection argument --- src/ansys/mapdl/core/launcher.py | 36 ++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 97375fb889..34aebe9d50 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1089,7 +1089,7 @@ def launch_mapdl( add_env_vars: Optional[Dict[str, str]] = None, replace_env_vars: Optional[Dict[str, str]] = None, version: Optional[Union[int, str]] = None, - detect_slurm_config: bool = True, + detect_HPC: bool = True, **kwargs: Dict[str, Any], ) -> Union[MapdlGrpc, "MapdlConsole"]: """Start MAPDL locally. @@ -1118,12 +1118,15 @@ def launch_mapdl( MAPDL jobname. Defaults to ``'file'``. nproc : int, optional - Number of processors. Defaults to 2. + Number of processors. Defaults to 2. If running on an HPC cluster, + this value is adjusted to the number of CPUs allocated to the job, + unless ``detect_HPC`` is set to "false". ram : float, optional - Total size in megabytes of the workspace (memory) used for the initial allocation. - The default is ``None``, in which case 2 GB (2048 MB) is used. To force a fixed size - throughout the run, specify a negative number. + Total size in megabytes of the workspace (memory) used for the initial + allocation. The default is ``None``, in which case 2 GB (2048 MB) is + used. To force a fixed size throughout the run, specify a negative + number. mode : str, optional Mode to launch MAPDL. Must be one of the following: @@ -1276,6 +1279,13 @@ def launch_mapdl( export PYMAPDL_MAPDL_VERSION=22.2 + detect_HPC: bool, optional + Whether detect if PyMAPDL is running on an HPC cluster or not. Currently + only SLURM clusters are supported. By detaul, it is set to true. + This option can be bypassed if the environment variable + ``PYMAPDL_ON_SLURM`` is set to "true". For more information visit + :ref:`ref_hpc_slurm`. + kwargs : dict, optional These keyword arguments are interface specific or for development purposes. See Notes for more details. @@ -1447,6 +1457,12 @@ def launch_mapdl( "ANSYSLMD_LICENSE_FILE":"1055@MYSERVER"} >>> mapdl = launch_mapdl(replace_env_vars=my_env_vars) """ + # Checking specific env var + if not nproc: + nproc = os.environ.get("PYMAPDL_NPROC", None) + if nproc: + nproc = int(nproc) + # By default ON_SLURM = os.environ.get("PYMAPDL_ON_SLURM", None) if ON_SLURM is None: @@ -1462,7 +1478,7 @@ def launch_mapdl( and bool(os.environ.get("SLURM_JOB_ID", "")) ) - if detect_slurm_config and ON_SLURM: + if detect_HPC and ON_SLURM: LOG.info("On Slurm mode.") # extracting parameters @@ -2134,7 +2150,7 @@ def get_value( # ntasks is for mpi SLURM_NTASKS = get_value("SLURM_NTASKS", kwargs) LOG.info(f"SLURM_NTASKS: {SLURM_NTASKS}") - # Sharing tasks acrros multiple nodes (DMP) + # Sharing tasks across multiple nodes (DMP) # the format of this envvar is a bit tricky. Avoiding it for the moment. # SLURM_TASKS_PER_NODE = int( # kwargs.pop( @@ -2178,12 +2194,6 @@ def get_value( jobname = os.environ.get("SLURM_JOB_NAME", "file") LOG.info(f"Using jobname: {jobname}") - # Checking specific env var - if not nproc: - nproc = os.environ.get("PYMAPDL_NPROC", None) - if nproc: - nproc = int(nproc) - if not nproc: ## Attempt to calculate the appropriate number of cores: # Reference: https://stackoverflow.com/a/51141287/6650211 From d9e3b0d7ad0cd81fce5f256d71c5afbf289b9b8a Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:22:00 +0000 Subject: [PATCH 17/35] docs: adding documentation --- .../extended_examples/hpc/hpc_ml_ga.rst | 2 +- doc/source/user_guide/hpc/pymapdl.rst | 168 +++++++++++++----- doc/source/user_guide/hpc/settings.rst | 49 +++-- doc/source/user_guide/hpc/troubleshooting.rst | 110 +++++++++--- 4 files changed, 244 insertions(+), 85 deletions(-) diff --git a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst b/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst index 30570b5c6b..fb87bb7e6d 100644 --- a/doc/source/examples/extended_examples/hpc/hpc_ml_ga.rst +++ b/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 ` file. diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index e0fddefa78..c70628f3a7 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -1,84 +1,168 @@ -.. _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: + +* `Submit a PyMAPDL batch job to the cluster from the entrypoint node` + + +Since v0.68.5, PyMAPDL can take advantage of the tigh 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 will launch an MAPDL instance which will use 32 cores +spawning across those 8 nodes. +This behaviour can disabled if passing the environment variable +:envvar:`PYMAPDL_ON_SLURM` or passing the argument `detect_HPC=False` +to :func:`launch_mapdl() `. + + + +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`` file + + #!/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 CPUs: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') mapdl.exit() +You can just run in your console: -**Bash script:** ``job.sh`` +.. code-block:: console -.. code-block:: bash + (venv) user@entrypoint-machine:~$ sbatch main.py - source /home/user/.venv/bin/activate - python pymapdl_script.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 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 CPUs SLURM job, you can use: -.. code-block:: console +.. code-block:: bash + + (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py - user@machine:~$ source /home/user/.venv/bin/activate - (.venv) user@machine:~$ srun pymapdl_script.py --export=ALL -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: +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`` python script + + 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.prep7() + n_proc = mapdl.get_value("ACTIVE", 0, "NUMCPU") + print(f"Number of CPUs: {n_proc}") + + mapdl.exit() + + +.. code-block:: bash + :caption: ``job.sh`` execution script + + 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 + +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. diff --git a/doc/source/user_guide/hpc/settings.rst b/doc/source/user_guide/hpc/settings.rst index 7f6af61c63..f4366ab6f0 100644 --- a/doc/source/user_guide/hpc/settings.rst +++ b/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,11 +58,20 @@ 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 @@ -67,11 +79,13 @@ You can then create the virtual environment in the ``/home/user/.venv`` director 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,8 +121,8 @@ 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 @@ -116,5 +130,6 @@ On the console, you should see this output: 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`. + diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 3a41a60537..8f84a202df 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -7,8 +7,19 @@ Troubleshooting Debugging jobs -------------- -- Use ``--output`` and ``--error`` directives in batch scripts to capture - standard output and error messages. +- Use ``--output`` and ``--error`` directives in batch scripts to captures + standard output and error messages to specific files. + + .. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --output=ansys_job.out # Standard output file + #SBATCH --error=ansys_job.err # Standard error file + + source /home/user/pymapdl/.venv/bin/activate + python /home/user/pymapdl.py - Check SLURM logs for error messages and debugging information. @@ -19,44 +30,90 @@ Python virtual environment is not accessible -------------------------------------------- If there is an error while testing the Python installation, it might mean that the Python environment is not accessible to the compute nodes. -For example, in the following output, PyMAPDL could not be found, meaning that the script -is not using the virtual environment (``/home/user/.venv``): +For example, given the following *bash* script `test.sh`: + +.. code-block:: bash + + source /home/user/.venv/bin/activate + python -c "from ansys.mapdl import core as pymapdl; pymapdl.report()" + +The following output is shown after running in the terminal: .. code-block:: console user@machine:~$ srun test.sh + Testing Python! Traceback (most recent call last): File "", line 1, in ImportError: No module named ansys.mapdl -This could be for a number of reasons. One of them is that the system Python distribution -used to create the virtual environment is not accessible from the compute nodes +As the output shows, PyMAPDL could not be found, meaning that either: +* The virtual environment does not have PyMAPDL installed. + See :ref:`ref_install_pymapdl_on_hpc`. +* Or the script did not activate properly the virtual environment + (``/home/user/.venv``). + +For the second reason, there could be a number of reasons. +One of them is that the system Python distribution used to create +the virtual environment is not accessible from the compute nodes due to one of these reasons: - The virtual environment has been created in a directory that is not accessible from the nodes. -- The virtual environment has been created from a Python - executable that is not available to the compute nodes. - Hence, the virtual environment is not activated. For - example, you might be creating the virtual environment - using Python 3.10, but only Python 3.8 is available - from the compute nodes. - -You can test which Python executable the cluster is using by starting an interactive session in -a compute node with this code: + In this case, your terminal might also show that the + ``activate`` file could not be found. + + .. code-block:: console + + user@machine:~$ srun test.sh + Testing Python! + bash: .venv/bin/activate: No such file or directory + + Depending on your terminal configuration, the above error might be sufficient + to exit the terminal process, or not. + If not, the execution will continue, and the subsequent ``python`` call will + be executed using the default python executable. + It is very likely that the default ``python`` executable does not have + PyMAPDL installed, hence the ``ImportError`` error showed above might appear + too. + +- The virtual environment has been created from a Python executable that is + not available to the compute nodes. Hence, the virtual environment is not + activated. + For example, you might be creating the virtual environment Using + Python 3.10, but only Python 3.8 is available from the compute nodes. + You can test which Python executable the cluster is using by starting an + interactive session in a compute node with this code to list all commands + which starts with ``python``: .. code-block:: console user@machine:~$ srun --pty /bin/bash - user@compute_node_01:~$ compgen -c | grep python # List all commands starting with python + user@compute_node_01:~$ compgen -c | grep python .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch +It should be noticed the above approach assumes that all the nodes have similar +configuration, hence all of them should have the same Python installations +available. + +It is also convenient to be aware that environment variable modules can be +used to activate Python installations. +For more information, see :ref:`ref_envvar_modules_on_hpc`. + + +.. _ref_envvar_modules_on_hpc: + +Using modules to load Python +---------------------------- + Many HPC infrastructures use environment managers to load and unload -software packages using modules and environment variables. -Hence, you might want to make sure that the correct module is loaded in your script. +software packages using modules and environment variables. +Hence, you might want to make sure that the correct module is loaded in your +script. + For information on two of the most common environment managers, see the `Modules documentation `_ and `Lmod documentation `_. Check your cluster documentation to know which environment @@ -76,12 +133,14 @@ Using the Ansys-provided Python installation **For development purposes only** -In certain HPC environments the possibility of installing a different Python version -is limited for security reasons. In such cases, the Python distribution available in -the Ansys installation can be used. -This Python distribution is a customized Python (CPython) -version for Ansys products use only. Its use is **discouraged** -except for very advanced users and special use cases. +In certain HPC environments the possibility of installing a different Python +version is limited for security reasons. +In such cases, the Python distribution available in the Ansys installation +can be used. +This Python distribution is a customized Python (CPython) version for Ansys +products use only. +Its use is **discouraged** except for very advanced users and special use +cases. This Python distribution is in the following directory, where ``%MAPDL_VERSION%`` is the three-digit Ansys version: @@ -98,7 +157,8 @@ For example, here is the directory for Ansys 2024 R2: In Ansys 2024 R1 and later, the unified installer includes CPython 3.10. -Earlier versions include CPython 3.7 (``/commonfiles/CPython/3_7/linx64/Release/python``). +Earlier versions include CPython 3.7 +(``/commonfiles/CPython/3_7/linx64/Release/python``). Because the Ansys installation must be available to all the compute nodes to run simulations using them, this From 34bcfc4531c450eb92510abda3ad049a47ce3c6b Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 7 Oct 2024 11:34:40 +0000 Subject: [PATCH 18/35] chore: adding changelog file 3466.documentation.md --- doc/changelog.d/3466.documentation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changelog.d/3466.documentation.md diff --git a/doc/changelog.d/3466.documentation.md b/doc/changelog.d/3466.documentation.md new file mode 100644 index 0000000000..902767602d --- /dev/null +++ b/doc/changelog.d/3466.documentation.md @@ -0,0 +1 @@ +feat: passing tight integration env vars to mapdl \ No newline at end of file From 3bc1cc672bb61c8275ee3d1079a697dc168c283d Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 12:36:55 +0000 Subject: [PATCH 19/35] fix: vale issues --- doc/source/user_guide/hpc/pymapdl.rst | 16 ++++++++-------- doc/source/user_guide/hpc/troubleshooting.rst | 14 +++++++------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index c70628f3a7..f24134509f 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -29,9 +29,9 @@ 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 will launch an MAPDL instance which will use 32 cores +then PyMAPDL launches an MAPDL instance which uses 32 cores spawning across those 8 nodes. -This behaviour can disabled if passing the environment variable +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() `. @@ -73,7 +73,7 @@ For instance, to launch the following Python script ``main.py``: mapdl = launch_mapdl(run_location="/home/ubuntu/tmp/tmp/mapdl", loglevel="debug") print(mapdl.prep7()) - print(f'Number of CPUs: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') + print(f'Number of CPU: {mapdl.get_value("ACTIVE", 0, "NUMCPU")}') mapdl.exit() @@ -90,7 +90,7 @@ Python executable call: (venv) user@entrypoint-machine:~$ sbatch python main.py -Additionally, you can can change the amount of cores used in your +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 @@ -105,7 +105,7 @@ You can also add ``sbatch`` options to the command: For instance, to launch a PyMAPDL job which start a four cores MAPDL instance -on a 10 CPUs SLURM job, you can use: +on a 10 CPU SLURM job, you can use: .. code-block:: bash @@ -129,12 +129,12 @@ In this case, you must create two files: from ansys.mapdl.core import launch_mapdl # Number of processors must be lower than the - # number of CPUs allocated for the job. + # 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 CPUs: {n_proc}") + print(f"Number of CPU: {n_proc}") mapdl.exit() @@ -158,7 +158,7 @@ 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 diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 8f84a202df..9e79d0fc8b 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -70,13 +70,13 @@ due to one of these reasons: Testing Python! bash: .venv/bin/activate: No such file or directory - Depending on your terminal configuration, the above error might be sufficient - to exit the terminal process, or not. - If not, the execution will continue, and the subsequent ``python`` call will - be executed using the default python executable. + Depending on your terminal configuration, the preceding error might be + sufficient to exit the terminal process, or not. + If not, the execution continues, and the subsequent ``python`` call is + executed using the default python executable. It is very likely that the default ``python`` executable does not have - PyMAPDL installed, hence the ``ImportError`` error showed above might appear - too. + PyMAPDL installed, hence the ``ImportError`` error showed preceding might + appear too. - The virtual environment has been created from a Python executable that is not available to the compute nodes. Hence, the virtual environment is not @@ -95,7 +95,7 @@ due to one of these reasons: .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch -It should be noticed the above approach assumes that all the nodes have similar +It should be noticed the preceding approach assumes that all the nodes have similar configuration, hence all of them should have the same Python installations available. From 0f1606bfed514f0e556207e97c03a8f7c840bac9 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 14:03:57 +0000 Subject: [PATCH 20/35] docs: fix vale --- doc/source/user_guide/hpc/pymapdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index f24134509f..5a3faa9962 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -24,7 +24,7 @@ Currently, the supported configurations are: * `Submit a PyMAPDL batch job to the cluster from the entrypoint node` -Since v0.68.5, PyMAPDL can take advantage of the tigh integration +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. From 89552c9b4eae3eedf658e84f6e30d47816208c65 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 15:56:36 +0200 Subject: [PATCH 21/35] docs: expanding a bit troubleshooting advices and small format fix --- doc/source/user_guide/hpc/pymapdl.rst | 11 ++++--- doc/source/user_guide/hpc/troubleshooting.rst | 31 ++++++++++++++++--- doc/source/user_guide/troubleshoot.rst | 1 + 3 files changed, 34 insertions(+), 9 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index 5a3faa9962..322621948b 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -21,7 +21,7 @@ or not (``batch`` mode). Currently, the supported configurations are: -* `Submit a PyMAPDL batch job to the cluster from the entrypoint node` +* :ref:`ref_pymapdl_batch_in_cluster_hpc` Since v0.68.5, PyMAPDL can take advantage of the tight integration @@ -36,6 +36,7 @@ This behaviour can turn off if passing the environment variable to :func:`launch_mapdl() `. +.. _ref_pymapdl_batch_in_cluster_hpc: Submit a PyMAPDL batch job to the cluster from the entrypoint node ================================================================== @@ -64,7 +65,7 @@ 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`` file + :caption: main.py #!/usr/bin/env python3 @@ -107,7 +108,7 @@ You can also add ``sbatch`` options to the command: 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:: bash +.. code-block:: console (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch --partition=qsmall --nodes=10 --ntasks-per-node=1 main.py @@ -124,7 +125,7 @@ In this case, you must create two files: Python script. .. code-block:: python - :caption: ``main.py`` python script + :caption: main.py from ansys.mapdl.core import launch_mapdl @@ -140,7 +141,7 @@ In this case, you must create two files: .. code-block:: bash - :caption: ``job.sh`` execution script + :caption: job.sh source /home/user/.venv/bin/activate python main.py diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 9e79d0fc8b..528c00fea9 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -22,6 +22,26 @@ Debugging jobs python /home/user/pymapdl.py - Check SLURM logs for error messages and debugging information. +- It is also good idea to print the environment variables in your bash script, using + ``printenv``. Additionally, you can filter them using ``grep``. + + .. code-block:: bash + + #!/bin/bash + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --output=ansys_job.out # Standard output file + #SBATCH --error=ansys_job.err # Standard error file + + printenv | grep "PYMAPDL" # Print env vars which contains 'PYMAPDL' + printenv | grep "SLURM" # Print env vars which contains 'SLURM' + source /home/user/pymapdl/.venv/bin/activate + python /home/user/pymapdl.py + +- Use PyMAPDL logging to printout valuable information. To activate this, see + :ref:`ref_debug_pymapdl`. + +- In case you need more help, visit :ref:`ref_troubleshooting`. .. _ref_python_venv_not_accesible: @@ -49,8 +69,10 @@ The following output is shown after running in the terminal: ImportError: No module named ansys.mapdl As the output shows, PyMAPDL could not be found, meaning that either: + * The virtual environment does not have PyMAPDL installed. See :ref:`ref_install_pymapdl_on_hpc`. + * Or the script did not activate properly the virtual environment (``/home/user/.venv``). @@ -59,10 +81,9 @@ One of them is that the system Python distribution used to create the virtual environment is not accessible from the compute nodes due to one of these reasons: -- The virtual environment has been created in a - directory that is not accessible from the nodes. - In this case, your terminal might also show that the - ``activate`` file could not be found. +- The virtual environment has been created in a directory that is + not accessible from the nodes. In this case, your terminal might + also show that the ``activate`` file could not be found. .. code-block:: console @@ -176,6 +197,8 @@ the compute nodes: user@machine:~$ export PY_PATH=/ansys_inc/v241/commonfiles/CPython/3_10/linx64/Release/Python + This path needs to be adapted to where Ansys is installed and also which version is used. + #. For only Ansys 2024 R1 and earlier, patch the ``PATH`` and ``LD_LIBRARY_PATH`` environment variables: diff --git a/doc/source/user_guide/troubleshoot.rst b/doc/source/user_guide/troubleshoot.rst index 54cf12d0c7..74a2b63f35 100644 --- a/doc/source/user_guide/troubleshoot.rst +++ b/doc/source/user_guide/troubleshoot.rst @@ -8,6 +8,7 @@ Troubleshooting PyMAPDL To help you resolve any problems that you might have when using PyMAPDL, some of the most common problems and frequently asked questions are posted here. +.. _ref_debug_pymapdl: Debug in PyMAPDL ---------------- From c3c6506760a5bf1f09d92fc33d044ddcfc229e77 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 16:42:24 +0200 Subject: [PATCH 22/35] fix: nproc tests --- src/ansys/mapdl/core/launcher.py | 1 + tests/test_launcher.py | 23 +++++++++++++++++------ 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 34aebe9d50..18fa51c27e 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -2295,4 +2295,5 @@ def pack_parameters(locals_var): dict_["start_instance"] = locals_var["start_instance"] dict_["version"] = locals_var["version"] dict_["additional_switches"] = locals_var["additional_switches"] + dict_["nproc"] = locals_var["nproc"] return dict_ diff --git a/tests/test_launcher.py b/tests/test_launcher.py index 5be0570c31..1b66a59863 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -604,7 +604,6 @@ def test_deprecate_verbose(): ), pytest.param( { - "PYMAPDL_NPROC": 5, "SLURM_JOB_NAME": "myawesomejob", "SLURM_NTASKS": 2, "SLURM_CPUS_PER_TASK": 2, @@ -613,12 +612,11 @@ def test_deprecate_verbose(): "SLURM_MEM_PER_NODE": None, "SLURM_NODELIST": None, }, - {"nproc": 5, "jobname": "myawesomejob"}, - id="Testing PYMAPDL_NPROC and SLURM_JOB_NAME", + {"nproc": 4, "jobname": "myawesomejob"}, + id="Testing SLURM_JOB_NAME", ), pytest.param( { - "PYMAPDL_NPROC": 5, "SLURM_JOB_NAME": "myawesomejob", "SLURM_NTASKS": 2, "SLURM_CPUS_PER_TASK": 2, @@ -628,8 +626,8 @@ def test_deprecate_verbose(): "SLURM_NODELIST": None, "PYMAPDL_MAPDL_EXEC": "asdf/qwer/poiu", }, - {"nproc": 5, "jobname": "myawesomejob", "exec_file": "asdf/qwer/poiu"}, - id="Testing PYMAPDL_NPROC and SLURM_JOB_NAME", + {"nproc": 4, "jobname": "myawesomejob", "exec_file": "asdf/qwer/poiu"}, + id="Testing PYMAPDL_MAPDL_EXEC and SLURM_JOB_NAME", ), ), indirect=["set_env_var_context"], @@ -782,3 +780,16 @@ def test_ip_and_start_instance( assert options["ip"] == ip else: assert options["ip"] in (LOCALHOST, "0.0.0.0") + + +def test_nproc_envvar(monkeypatch): + monkeypatch.setenv("PYMAPDL_NPROC", 10) + args = launch_mapdl(_debug_no_launch=True) + assert args["nproc"] == 10 + + +@pytest.mark.parametrize("nproc,result", [[None, 2], [5, 5]]) +def test_nproc(monkeypatch, nproc, result): + monkeypatch.delenv("PYMAPDL_START_INSTANCE") + args = launch_mapdl(nproc=nproc, _debug_no_launch=True) + assert args["nproc"] == result From db963c4a111b493da90d451192a34572bc30856c Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 17:37:08 +0200 Subject: [PATCH 23/35] revert: "chore: To fix sphinx build" This reverts commit e45d2e5d4fb97359605f445f462fa4b9cf76515a. --- .github/workflows/ci.yml | 1 - doc/changelog.d/3468.fixed.md | 1 - doc/source/conf.py | 3 ++- 3 files changed, 2 insertions(+), 3 deletions(-) delete mode 100644 doc/changelog.d/3468.fixed.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 543cc91b08..30f1396175 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,7 +34,6 @@ 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%-... diff --git a/doc/changelog.d/3468.fixed.md b/doc/changelog.d/3468.fixed.md deleted file mode 100644 index ab369c1e41..0000000000 --- a/doc/changelog.d/3468.fixed.md +++ /dev/null @@ -1 +0,0 @@ -fix: add ``build cheatsheet`` as env variable within doc-build \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index d4e73a7a0b..040d57eb7e 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -321,7 +321,8 @@ "title": "PyMAPDL cheat sheet", "version": f"v{version}", "pages": ["getting_started/learning"], - } + }, +} html_context = { "display_github": True, # Integrate GitHub From 1e315196b49ea731e97da031096c55a01e01eb0d Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 7 Oct 2024 15:45:37 +0000 Subject: [PATCH 24/35] docs: clarifying where everything is running. --- doc/source/user_guide/hpc/pymapdl.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index 322621948b..75468bfb87 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -49,7 +49,9 @@ 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. +PyMAPDL job from the entrypoint is very easy to do using ``sbatch`` command. +Using ``sbatch`` command, the PyMAPDL runs and launches an MAPDL instance in +the compute nodes. 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. From 5c7967c843a0596adbfad872b7f74f60f748f92a Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 8 Oct 2024 08:51:19 +0200 Subject: [PATCH 25/35] docs: expanding bash example --- doc/source/user_guide/hpc/pymapdl.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index 75468bfb87..6f66ec52ca 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -145,7 +145,20 @@ In this case, you must create two files: .. code-block:: bash :caption: job.sh + #!/bin/bash + # Set SLURM options + #SBATCH --job-name=ansys_job # Job name + #SBATCH --partition=qsmall # Specify the queue/partition name + #SBATCH --nodes=5 # Number of nodes + #SBATCH --ntasks-per-node=2 # Number of tasks (cores) per node + #SBATCH --time=04:00:00 # Set a time limit for the job (optional but recommended) + + # Set env vars + export MY_ENV_VAR=VALUE + + # Activating Python virtual environment source /home/user/.venv/bin/activate + # Calling Python script python main.py To start the simulation, you use this code: From 880a6b8e971f71536e0739e7de4abcf90b29184b Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Tue, 15 Oct 2024 13:30:46 +0200 Subject: [PATCH 26/35] tests: fix --- tests/test_launcher.py | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/tests/test_launcher.py b/tests/test_launcher.py index dee9aa7360..684cfa4763 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -24,9 +24,9 @@ import os import tempfile +from unittest.mock import patch import warnings -import psutil import pytest from ansys.mapdl import core as pymapdl @@ -479,13 +479,6 @@ def test_launching_on_busy_port(mapdl): launch_mapdl(port=mapdl.port) -@requires("local") -def test_cpu_checks(): - machine_cores = psutil.cpu_count(logical=False) - with pytest.raises(NotEnoughResources): - launch_mapdl(nproc=machine_cores + 2) - - def test_fail_channel_port(): with pytest.raises(ValueError): launch_mapdl(channel="something", port="something") @@ -783,14 +776,24 @@ def test_ip_and_start_instance( assert options["ip"] in (LOCALHOST, "0.0.0.0") +def mycpucount(**kwargs): + return 10 # faking 10 cores + + def test_nproc_envvar(monkeypatch): monkeypatch.setenv("PYMAPDL_NPROC", 10) args = launch_mapdl(_debug_no_launch=True) assert args["nproc"] == 10 -@pytest.mark.parametrize("nproc,result", [[None, 2], [5, 5]]) -def test_nproc(monkeypatch, nproc, result): - monkeypatch.delenv("PYMAPDL_START_INSTANCE") - args = launch_mapdl(nproc=nproc, _debug_no_launch=True) - assert args["nproc"] == result +@pytest.mark.parametrize("nproc", [None, 5, 9, 15]) +@patch("psutil.cpu_count", mycpucount) +def test_nproc(monkeypatch, nproc): + monkeypatch.delenv("PYMAPDL_START_INSTANCE", False) + + if nproc and nproc > mycpucount(): + with pytest.raises(NotEnoughResources): + launch_mapdl(nproc=nproc, _debug_no_launch=True) + else: + args = launch_mapdl(nproc=nproc, _debug_no_launch=True) + assert args["nproc"] == (nproc or 2) From 7514c31a0cb470b57a4f930371131932a23d954a Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 17 Oct 2024 10:28:43 +0200 Subject: [PATCH 27/35] docs: adding `PYMAPDL_NPROC` to env var section --- doc/source/user_guide/mapdl.rst | 179 ++++++++++++++++++-------------- 1 file changed, 101 insertions(+), 78 deletions(-) diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index bfc59931b5..3b967f0852 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -1097,83 +1097,106 @@ Environment variables ===================== There are several PyMAPDL-specific environment variables that can be -used to control the behavior or launching of PyMAPDL and MAPDL. +used to control the default behavior of PyMAPDL or launching MAPDL. + +It should be mentioned that these environment variables do not have +priority over the arguments given in the corresponding functions. +For instance: + +.. code-block:: console + + user@machine:~$ export PYMAPDL_PORT=50052 + user@machine:~$ python -c "from ansys.mapdl.core import launch_mapdl; mapdl=launch_mapdl(port=60053)" + +The above command will launch an MAPDL instance on the port 60053, +because the argument ``port`` has priority over the environment +variable :envvar:`PYMAPDL_PORT`. + These are described in the following table: -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_START_INSTANCE` | Override the behavior of the | -| | :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``. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export PYMAPDL_START_INSTANCE=True | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_PORT` | Default port for PyMAPDL to connect to. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export PYMAPDL_PORT=50052 | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_IP` | Default IP for PyMAPDL to connect to. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export PYMAPDL_IP=123.45.67.89 | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`ANSYSLMD_LICENSE_FILE` | License file or IP address with port in the format | -| | ``PORT@IP``. Do not confuse with the ``IP`` and | -| | ``PORT`` where the MAPDL instance is running, which | -| | are specified using :envvar:`PYMAPDL_IP` and | -| | :envvar:`PYMAPDL_PORT`. | -| | This is helpful for supplying licensing for | -| | Docker. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export ANSYSLMD_LICENSE_FILE=1055@123.45.67.89 | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_MAPDL_EXEC` | Executable path from where to launch MAPDL | -| | instances. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export PYMAPDL_MAPDL_EXEC=/ansys_inc/v241/ansys/bin/mapdl | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_MAPDL_VERSION` | Default MAPDL version to launch in case there | -| | are several versions availables. | -| | | -| | **Example:** | -| | | -| | .. code:: console | -| | | -| | export PYMAPDL_MAPDL_VERSION=22.2 | -| | | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_ON_SLURM` | With this environment variable set to ``FALSE``, you can avoid | -| | PyMAPDL from detecting that it is running on a SLURM HPC cluster. | -+---------------------------------------+---------------------------------------------------------------------+ -| :envvar:`PYMAPDL_MAX_MESSAGE_LENGTH` | Maximum gRPC message length. If your | -| | connection terminates when running | -| | PRNSOL or NLIST, raise this. In bytes, | -| | defaults to 256 MB. | -| | | -| | Only for developing purposes. | -+---------------------------------------+---------------------------------------------------------------------+ ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_START_INSTANCE` | Override the behavior of the | +| | :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``. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_START_INSTANCE=True | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_PORT` | Default port for PyMAPDL to connect to. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_PORT=50052 | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_IP` | Default IP for PyMAPDL to connect to. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_IP=123.45.67.89 | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_NPROC` | Default number of cores for MAPDL to use. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_NPROC=10 | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`ANSYSLMD_LICENSE_FILE` | License file or IP address with port in the format | +| | ``PORT@IP``. Do not confuse with the ``IP`` and | +| | ``PORT`` where the MAPDL instance is running, which | +| | are specified using :envvar:`PYMAPDL_IP` and | +| | :envvar:`PYMAPDL_PORT`. | +| | This is helpful for supplying licensing for | +| | Docker. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export ANSYSLMD_LICENSE_FILE=1055@123.45.89 | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_MAPDL_EXEC` | Executable path from where to launch MAPDL | +| | instances. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_MAPDL_EXEC=/ansys_inc/v241/ansys/bin/mapdl | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_MAPDL_VERSION` | Default MAPDL version to launch in case there | +| | are several versions availables. | +| | | +| | **Example:** | +| | | +| | .. code-block:: console | +| | | +| | user@machine:~$ export PYMAPDL_MAPDL_VERSION=22.2 | +| | | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_ON_SLURM` | With this environment variable set to ``FALSE``, you can avoid | +| | PyMAPDL from detecting that it is running on a SLURM HPC cluster. | ++---------------------------------------+----------------------------------------------------------------------------------+ +| :envvar:`PYMAPDL_MAX_MESSAGE_LENGTH` | Maximum gRPC message length. If your | +| | connection terminates when running | +| | PRNSOL or NLIST, raise this. In bytes, | +| | defaults to 256 MB. | +| | | +| | Only for developing purposes. | ++---------------------------------------+----------------------------------------------------------------------------------+ From fdf00d180764549c1f033b97d4363f042db52cf3 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 17 Oct 2024 11:04:08 +0200 Subject: [PATCH 28/35] docs: fix vale issue --- doc/source/user_guide/mapdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index 3b967f0852..b3169e4dd5 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -1108,7 +1108,7 @@ For instance: user@machine:~$ export PYMAPDL_PORT=50052 user@machine:~$ python -c "from ansys.mapdl.core import launch_mapdl; mapdl=launch_mapdl(port=60053)" -The above command will launch an MAPDL instance on the port 60053, +The above command launches an MAPDL instance on the port 60053, because the argument ``port`` has priority over the environment variable :envvar:`PYMAPDL_PORT`. From 4aa477d1ec6b7208c05d7e682b5721b3a5aa92c2 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 17 Oct 2024 11:19:02 +0200 Subject: [PATCH 29/35] docs: fix vale issue --- doc/source/user_guide/mapdl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index b3169e4dd5..d60d8e610d 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -1108,7 +1108,7 @@ For instance: user@machine:~$ export PYMAPDL_PORT=50052 user@machine:~$ python -c "from ansys.mapdl.core import launch_mapdl; mapdl=launch_mapdl(port=60053)" -The above command launches an MAPDL instance on the port 60053, +The preceding command launches an MAPDL instance on the port 60053, because the argument ``port`` has priority over the environment variable :envvar:`PYMAPDL_PORT`. From 4dadc1d15e45b41b4ae169e5074659528648e7ce Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Thu, 17 Oct 2024 11:20:53 +0200 Subject: [PATCH 30/35] fix: replacing env var name --- tests/test_launcher.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tests/test_launcher.py b/tests/test_launcher.py index 4d516d904f..3f4acfa113 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -694,17 +694,17 @@ def test_slurm_ram(monkeypatch, ram, expected, context): @pytest.mark.parametrize("slurm_env_var", ["True", "false", ""]) @pytest.mark.parametrize("slurm_job_name", ["True", "false", ""]) @pytest.mark.parametrize("slurm_job_id", ["True", "false", ""]) -@pytest.mark.parametrize("detect_slurm_config", [True, False, None]) +@pytest.mark.parametrize("detect_HPC", [True, False, None]) def test_is_on_slurm( - monkeypatch, slurm_env_var, slurm_job_name, slurm_job_id, detect_slurm_config + monkeypatch, slurm_env_var, slurm_job_name, slurm_job_id, detect_HPC ): monkeypatch.setenv("PYMAPDL_ON_SLURM", slurm_env_var) monkeypatch.setenv("SLURM_JOB_NAME", slurm_job_name) monkeypatch.setenv("SLURM_JOB_ID", slurm_job_id) - flag = is_on_slurm(args={"detect_slurm_config": detect_slurm_config}) + flag = is_on_slurm(args={"detect_HPC": detect_HPC}) - if detect_slurm_config is not True: + if detect_HPC is not True: assert not flag else: @@ -720,7 +720,7 @@ def test_is_on_slurm( if ON_LOCAL: assert ( launch_mapdl( - detect_slurm_config=detect_slurm_config, + detect_HPC=detect_HPC, _debug_no_launch=True, )["ON_SLURM"] == flag From 60bf932184c30afa614b57147304e01e15fe2371 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Mon, 21 Oct 2024 11:09:33 +0200 Subject: [PATCH 31/35] fix: unit tests --- tests/test_launcher.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/test_launcher.py b/tests/test_launcher.py index d553320f6b..63ea33d1d3 100644 --- a/tests/test_launcher.py +++ b/tests/test_launcher.py @@ -28,6 +28,7 @@ from unittest.mock import patch import warnings +import psutil import pytest from ansys.mapdl import core as pymapdl @@ -885,6 +886,7 @@ def mycpucount(**kwargs): return 10 # faking 10 cores +@patch("psutil.cpu_count", mycpucount) def test_nproc_envvar(monkeypatch): monkeypatch.setenv("PYMAPDL_NPROC", 10) args = launch_mapdl(_debug_no_launch=True) From d027edde88f8cd8fb8313637289063a4a8c11e71 Mon Sep 17 00:00:00 2001 From: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com> Date: Mon, 21 Oct 2024 09:19:50 +0000 Subject: [PATCH 32/35] chore: adding changelog file 3466.documentation.md [dependabot-skip] --- doc/changelog.d/3466.documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog.d/3466.documentation.md b/doc/changelog.d/3466.documentation.md index 902767602d..7c211ed0d1 100644 --- a/doc/changelog.d/3466.documentation.md +++ b/doc/changelog.d/3466.documentation.md @@ -1 +1 @@ -feat: passing tight integration env vars to mapdl \ No newline at end of file +docs: documenting using pymapdl on clusters \ No newline at end of file From 0bb2f81b45f534c7aba8da38dfd07283db2f7328 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 23 Oct 2024 11:11:10 +0200 Subject: [PATCH 33/35] Apply suggestions from code review Co-authored-by: Camille <78221213+clatapie@users.noreply.github.com> --- doc/source/user_guide/hpc/pymapdl.rst | 2 +- doc/source/user_guide/hpc/troubleshooting.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index 6f66ec52ca..abadece7a6 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -14,7 +14,7 @@ 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 +This possibility opens 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). diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 528c00fea9..f545a5033a 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -73,7 +73,7 @@ As the output shows, PyMAPDL could not be found, meaning that either: * The virtual environment does not have PyMAPDL installed. See :ref:`ref_install_pymapdl_on_hpc`. -* Or the script did not activate properly the virtual environment +* Or the script did not properly activate the virtual environment (``/home/user/.venv``). For the second reason, there could be a number of reasons. @@ -102,7 +102,7 @@ due to one of these reasons: - The virtual environment has been created from a Python executable that is not available to the compute nodes. Hence, the virtual environment is not activated. - For example, you might be creating the virtual environment Using + For example, you might be creating the virtual environment using Python 3.10, but only Python 3.8 is available from the compute nodes. You can test which Python executable the cluster is using by starting an interactive session in a compute node with this code to list all commands From 4231a2e0ac1108b88c711d14dea621c5eb70e085 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 23 Oct 2024 18:07:16 +0200 Subject: [PATCH 34/35] docs: apply suggestions from code review made by Kathy Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/user_guide/hpc/pymapdl.rst | 62 +++++++++---------- doc/source/user_guide/hpc/settings.rst | 5 +- doc/source/user_guide/hpc/troubleshooting.rst | 46 +++++++------- doc/source/user_guide/mapdl.rst | 11 ++-- src/ansys/mapdl/core/launcher.py | 12 ++-- 5 files changed, 66 insertions(+), 70 deletions(-) diff --git a/doc/source/user_guide/hpc/pymapdl.rst b/doc/source/user_guide/hpc/pymapdl.rst index abadece7a6..c6d0a6c307 100644 --- a/doc/source/user_guide/hpc/pymapdl.rst +++ b/doc/source/user_guide/hpc/pymapdl.rst @@ -2,7 +2,7 @@ .. _ref_hpc_pymapdl_job: ======================= -PyMAPDL on HPC Clusters +PyMAPDL on HPC clusters ======================= @@ -10,18 +10,16 @@ Introduction ============ PyMAPDL communicates with MAPDL using the gRPC protocol. -This protocol offers many advantages and features, for more information +This protocol offers the many advantages and features described in 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. +One of these features is that it is not required to have both +PyMAPDL and MAPDL processes running on the same machine. This possibility opens 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) +on whether or not you run them both on the HPC compute nodes. +Additionally, you might be able interact with them (``interactive`` mode) or not (``batch`` mode). -Currently, the supported configurations are: - -* :ref:`ref_pymapdl_batch_in_cluster_hpc` +For information on supported configurations, see :ref:`ref_pymapdl_batch_in_cluster_hpc`. Since v0.68.5, PyMAPDL can take advantage of the tight integration @@ -31,9 +29,9 @@ 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() `. +This behavior can turn off if passing the :envvar:`PYMAPDL_ON_SLURM` +environment variable or passing the ``detect_HPC=False`` argument +to the :func:`launch_mapdl() ` function. .. _ref_pymapdl_batch_in_cluster_hpc: @@ -41,16 +39,16 @@ to :func:`launch_mapdl() `. 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 +Many HPC clusters allow their users to log into a machine using +``ssh``, ``vnc``, ``rdp``, or similar technologies and then submit a job to the cluster from there. -This entrypoint machine, sometimes known as *head node* or *entrypoint node*, +This entrypoint machine, sometimes known as the *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 from the entrypoint is very easy to do using ``sbatch`` command. -Using ``sbatch`` command, the PyMAPDL runs and launches an MAPDL instance in +PyMAPDL job from the entrypoint node is very easy to do using the ``sbatch`` command. +When the ``sbatch`` command is used, PyMAPDL runs and launches an MAPDL instance in the compute nodes. No changes are needed on a PyMAPDL script to run it on an SLURM cluster. @@ -61,10 +59,10 @@ First the virtual environment must be activated in the current terminal. user@entrypoint-machine:~$ export VENV_PATH=/my/path/to/the/venv user@entrypoint-machine:~$ source $VENV_PATH/bin/activate -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``). +Once the virtual environment is activated, you can launch any Python +script that has the proper Python shebang (``#!/usr/bin/env python3``). -For instance, to launch the following Python script ``main.py``: +For instance, assume that you want to launch the following ``main.py`` Python script: .. code-block:: python :caption: main.py @@ -80,21 +78,21 @@ For instance, to launch the following Python script ``main.py``: mapdl.exit() -You can just run in your console: +You can run this command in your console: .. code-block:: console (venv) user@entrypoint-machine:~$ sbatch main.py -Alternatively, you can remove the shebang from the python file and use a +Alternatively, you can remove the shebang from the Python file and use a Python executable call: .. code-block:: console (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. +Additionally, you can change the number of cores used in your +job by setting the :envvar:`PYMAPDL_NPROC` environment variable to the desired value. .. code-block:: console @@ -107,8 +105,8 @@ You can also add ``sbatch`` options to the command: (venv) user@entrypoint-machine:~$ PYMAPDL_NPROC=4 sbatch main.py -For instance, to launch a PyMAPDL job which start a four cores MAPDL instance -on a 10 CPU SLURM job, you can use: +For instance, to launch a PyMAPDL job that starts a four-core MAPDL instance +on a 10-CPU SLURM job, you can run this command: .. code-block:: console @@ -118,13 +116,13 @@ on a 10 CPU SLURM job, you can use: 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. +If you need to customize your PyMAPDL job further, you can create a SLURM +submission script for submitting it. 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. + Python script .. code-block:: python :caption: main.py @@ -156,9 +154,9 @@ In this case, you must create two files: # Set env vars export MY_ENV_VAR=VALUE - # Activating Python virtual environment + # Activate Python virtual environment source /home/user/.venv/bin/activate - # Calling Python script + # Call Python script python main.py To start the simulation, you use this code: @@ -170,7 +168,7 @@ To start the simulation, you use this code: 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 +The expected output of the job follows: .. code-block:: text diff --git a/doc/source/user_guide/hpc/settings.rst b/doc/source/user_guide/hpc/settings.rst index f4366ab6f0..225b37d1c9 100644 --- a/doc/source/user_guide/hpc/settings.rst +++ b/doc/source/user_guide/hpc/settings.rst @@ -10,13 +10,13 @@ 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**. +* **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**. + nodes.** For compatible Python versions, see :ref:`ref_pymapdl_installation`. Additionally, you must perform a few key steps to ensure efficient job @@ -123,6 +123,7 @@ then you can run that script using: 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 diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index f545a5033a..633927f86f 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -7,8 +7,8 @@ Troubleshooting Debugging jobs -------------- -- Use ``--output`` and ``--error`` directives in batch scripts to captures - standard output and error messages to specific files. +- Use ``--output`` and ``--error`` directives in batch scripts to capture + standard output and error messages to specific files: .. code-block:: bash @@ -41,7 +41,7 @@ Debugging jobs - Use PyMAPDL logging to printout valuable information. To activate this, see :ref:`ref_debug_pymapdl`. -- In case you need more help, visit :ref:`ref_troubleshooting`. +- If you need more help, see :ref:`ref_troubleshooting`. .. _ref_python_venv_not_accesible: @@ -50,14 +50,14 @@ Python virtual environment is not accessible -------------------------------------------- If there is an error while testing the Python installation, it might mean that the Python environment is not accessible to the compute nodes. -For example, given the following *bash* script `test.sh`: +For example, assume you have the following `test.sh` *bash* script: .. code-block:: bash source /home/user/.venv/bin/activate python -c "from ansys.mapdl import core as pymapdl; pymapdl.report()" -The following output is shown after running in the terminal: +The following output is shown after running this script in the terminal: .. code-block:: console @@ -68,18 +68,18 @@ The following output is shown after running in the terminal: File "", line 1, in ImportError: No module named ansys.mapdl -As the output shows, PyMAPDL could not be found, meaning that either: +As the output shows, PyMAPDL could not be found, indicating one of the following problems: * The virtual environment does not have PyMAPDL installed. See :ref:`ref_install_pymapdl_on_hpc`. -* Or the script did not properly activate the virtual environment +* The script did not properly activate the virtual environment (``/home/user/.venv``). -For the second reason, there could be a number of reasons. +The second problem can occur due to a number of reasons. One of them is that the system Python distribution used to create the virtual environment is not accessible from the compute nodes -due to one of these reasons: +because of one of these situations: - The virtual environment has been created in a directory that is not accessible from the nodes. In this case, your terminal might @@ -92,11 +92,10 @@ due to one of these reasons: bash: .venv/bin/activate: No such file or directory Depending on your terminal configuration, the preceding error might be - sufficient to exit the terminal process, or not. - If not, the execution continues, and the subsequent ``python`` call is - executed using the default python executable. - It is very likely that the default ``python`` executable does not have - PyMAPDL installed, hence the ``ImportError`` error showed preceding might + sufficient to exit the terminal process. If it is not, the execution continues, + and the subsequent ``python`` call is executed using the default Python executable. + It is very likely that the default Python executable does not have + PyMAPDL installed. Hence the ``ImportError`` error might appear too. - The virtual environment has been created from a Python executable that is @@ -106,7 +105,7 @@ due to one of these reasons: Python 3.10, but only Python 3.8 is available from the compute nodes. You can test which Python executable the cluster is using by starting an interactive session in a compute node with this code to list all commands - which starts with ``python``: + that start with ``python``: .. code-block:: console @@ -116,12 +115,11 @@ due to one of these reasons: .. the approach to solve this comes from: https://stackoverflow.com/questions/64188693/problem-with-python-environment-and-slurm-srun-sbatch -It should be noticed the preceding approach assumes that all the nodes have similar -configuration, hence all of them should have the same Python installations +It should be noted that the preceding approach assumes that all the nodes have similar +configurations. Hence, all of them should have the same Python installations available. -It is also convenient to be aware that environment variable modules can be -used to activate Python installations. +You can also use environment variable modules to activate Python installations. For more information, see :ref:`ref_envvar_modules_on_hpc`. @@ -158,10 +156,10 @@ In certain HPC environments the possibility of installing a different Python version is limited for security reasons. In such cases, the Python distribution available in the Ansys installation can be used. -This Python distribution is a customized Python (CPython) version for Ansys -products use only. -Its use is **discouraged** except for very advanced users and special use -cases. +This Python distribution is a customized Python (CPython) version for use only by Ansys +products. +Its use is **discouraged** unless you are a very advanced user or have a special use +case. This Python distribution is in the following directory, where ``%MAPDL_VERSION%`` is the three-digit Ansys version: @@ -178,7 +176,7 @@ For example, here is the directory for Ansys 2024 R2: In Ansys 2024 R1 and later, the unified installer includes CPython 3.10. -Earlier versions include CPython 3.7 +Earlier Ansys versions include CPython 3.7 (``/commonfiles/CPython/3_7/linx64/Release/python``). Because the Ansys installation must be available to all diff --git a/doc/source/user_guide/mapdl.rst b/doc/source/user_guide/mapdl.rst index d60d8e610d..c7ba053666 100644 --- a/doc/source/user_guide/mapdl.rst +++ b/doc/source/user_guide/mapdl.rst @@ -1099,20 +1099,19 @@ Environment variables There are several PyMAPDL-specific environment variables that can be used to control the default behavior of PyMAPDL or launching MAPDL. -It should be mentioned that these environment variables do not have +These environment variables do not have priority over the arguments given in the corresponding functions. -For instance: +Consider this command: .. code-block:: console user@machine:~$ export PYMAPDL_PORT=50052 user@machine:~$ python -c "from ansys.mapdl.core import launch_mapdl; mapdl=launch_mapdl(port=60053)" -The preceding command launches an MAPDL instance on the port 60053, -because the argument ``port`` has priority over the environment -variable :envvar:`PYMAPDL_PORT`. +This command launches an MAPDL instance on port 60053 +because the ``port`` argument has priority over the :envvar:`PYMAPDL_PORT` +environment variable. The following table describes all arguments. -These are described in the following table: +---------------------------------------+----------------------------------------------------------------------------------+ | :envvar:`PYMAPDL_START_INSTANCE` | Override the behavior of the | diff --git a/src/ansys/mapdl/core/launcher.py b/src/ansys/mapdl/core/launcher.py index 2e6b8bf12c..c6b6096a96 100644 --- a/src/ansys/mapdl/core/launcher.py +++ b/src/ansys/mapdl/core/launcher.py @@ -1143,15 +1143,15 @@ def launch_mapdl( export PYMAPDL_MAPDL_VERSION=22.2 detect_HPC: bool, optional - Whether detect if PyMAPDL is running on an HPC cluster or not. Currently - only SLURM clusters are supported. By detaul, it is set to true. - This option can be bypassed if the environment variable - ``PYMAPDL_ON_SLURM`` is set to "true". For more information visit + Whether detect if PyMAPDL is running on an HPC cluster. Currently + only SLURM clusters are supported. By default, it is set to true. + This option can be bypassed if the ``PYMAPDL_ON_SLURM`` + environment variable is set to "true". For more information, see :ref:`ref_hpc_slurm`. kwargs : dict, optional - These keyword arguments are interface specific or for - development purposes. See Notes for more details. + These keyword arguments are interface-specific or for + development purposes. For more information, see Notes. set_no_abort : :class:`bool` *(Development use only)* From 300446ef06224a6b68b7b386afc4007ca8464fe3 Mon Sep 17 00:00:00 2001 From: German <28149841+germa89@users.noreply.github.com> Date: Wed, 23 Oct 2024 18:09:24 +0200 Subject: [PATCH 35/35] docs: adding Kathy suggestion. --- doc/source/user_guide/hpc/troubleshooting.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/source/user_guide/hpc/troubleshooting.rst b/doc/source/user_guide/hpc/troubleshooting.rst index 528c00fea9..e951b49015 100644 --- a/doc/source/user_guide/hpc/troubleshooting.rst +++ b/doc/source/user_guide/hpc/troubleshooting.rst @@ -23,7 +23,8 @@ Debugging jobs - Check SLURM logs for error messages and debugging information. - It is also good idea to print the environment variables in your bash script, using - ``printenv``. Additionally, you can filter them using ``grep``. + ``printenv`` *bash* command. + Additionally, you can filter its output using ``grep`` *bash* command. .. code-block:: bash