From 773ddb7dd10a7f4283fc62ee4f37a8e1f8f582bf Mon Sep 17 00:00:00 2001 From: German Date: Thu, 21 Dec 2023 18:34:24 +0100 Subject: [PATCH] adding docs --- doc/source/getting_started/cli.rst | 276 ++++++++++++++++++++++++ doc/source/getting_started/index.rst | 1 + doc/source/getting_started/launcher.rst | 3 + doc/source/user_guide/convert.rst | 2 + 4 files changed, 282 insertions(+) create mode 100644 doc/source/getting_started/cli.rst diff --git a/doc/source/getting_started/cli.rst b/doc/source/getting_started/cli.rst new file mode 100644 index 0000000000..d3b1a5208e --- /dev/null +++ b/doc/source/getting_started/cli.rst @@ -0,0 +1,276 @@ + +.. _ref_cli: + +============================== +PyMAPDL command line interface +============================== + +For your convenience, PyMAPDL package includes a command line interface +which allows you to launch, stop and list local MAPDL instances. + + +Launch MAPDL instances +====================== + +To start MAPDL, just type on your activated virtual environment: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl + Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052 + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl + Success: Launched an MAPDL instance (PID=23644) at 127.0.0.1:50052 + +If you want to specify an argument, for instance the port, then you need to call +`launch_mapdl start`: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl start --port 50054 + Success: Launched an MAPDL instance (PID=18238) at 127.0.0.1:50054 + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl start --port 50054 + Success: Launched an MAPDL instance (PID=18238) at 127.0.0.1:50054 + + +This command `launch_mapdl start` aims to replicate the function +:func:`ansys.mapdl.core.launcher.launch_mapdl`, hence you can use +some of the arguments which this function allows. +For instance, you could specify the working directory: + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl start --run_location C:\Users\user\temp\ + Success: Launched an MAPDL instance (PID=32612) at 127.0.0.1:50052 + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl start --run_location /home/user/tmp + Success: Launched an MAPDL instance (PID=32612) at 127.0.0.1:50052 + + +For more information see :func:`ansys.mapdl.core.launcher.launch_mapdl`, +and :func:`ansys.mapdl.core.cli.launch_mapdl` + + +Stop MAPDL instances +==================== +MAPDL instances can be stopped by using `launch_mapdl stop` command in the following +way: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl stop + Success: Ansys instances running on port 50052 have been stopped. + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl stop + Success: Ansys instances running on port 50052 have been stopped. + + +By default, the instance running on the port `50052` is stopped. + +You can specify the instance running on a different port using `--port` argument: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl stop --port 50053 + Success: Ansys instances running on port 50053 have been stopped. + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl stop --port 50053 + Success: Ansys instances running on port 50053 have been stopped. + + +Or an instance with a given process id (PID): + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl stop --pid 40952 + Success: The process with PID 40952 and its children have been stopped. + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl stop --pid 40952 + Success: The process with PID 40952 and its children have been stopped. + + +Alternatively, you can stop all the running instances by using: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl stop --all + Success: Ansys instances have been stopped. + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl stop --all + Success: Ansys instances have been stopped. + + +List MAPDL instances and processes +================================== + +You can also list MAPDL instances and processes. +If you want to list MAPDL process, just use the following command: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl list + Name Is Instance Status gRPC port PID + ------------ ------------- -------- ----------- ----- + ANSYS.exe False running 50052 35360 + ANSYS.exe False running 50052 37116 + ANSYS222.exe True running 50052 41644 + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl list + Name Is Instance Status gRPC port PID + ------------ ------------- -------- ----------- ----- + ANSYS.exe False running 50052 35360 + ANSYS.exe False running 50052 37116 + ANSYS222.exe True running 50052 41644 + + +If you want, to just list the instances (avoiding listing children MAPDL +processes), just type: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl list -i + Name Status gRPC port PID + ------------ -------- ----------- ----- + ANSYS222.exe running 50052 41644 + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl list -i + Name Status gRPC port PID + ------------ -------- ----------- ----- + ANSYS222.exe running 50052 41644 + + +You can also print other fields like the working directory (using `--cwd`) +or the command line (using `-c`). +Additionally, you can also print all the available information by using the +argument `--long` or `-l`: + + +.. tab-set:: + + .. tab-item:: Windows + :sync: key1 + + .. code:: pwsh-session + + (.venv) PS C:\Users\user\pymapdl> launch_mapdl list -l + Name Is Instance Status gRPC port PID Command line Working directory + ------------ ------------- -------- ----------- ----- -------------------------------------------------------------------------------------------------------------------------------- --------------------------------------------------- + ANSYS.exe False running 50052 35360 C:\Program Files\ANSYS Inc\v222\ANSYS\bin\winx64\ANSYS.EXE -j file -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp + ANSYS.exe False running 50052 37116 C:\Program Files\ANSYS Inc\v222\ANSYS\bin\winx64\ANSYS.EXE -j file -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp + ANSYS222.exe True running 50052 41644 C:\Program Files\ANSYS Inc\v222\ansys\bin\winx64\ansys222.exe -j file -np 2 -b -i .__tmp__.inp -o .__tmp__.out -port 50052 -grpc C:\Users\User\AppData\Local\Temp\ansys_ahmfaliakp + + .. tab-item:: Linux + :sync: key1 + + .. code:: console + + (.venv) user@machine:~$ launch_mapdl list -l + Name Is Instance Status gRPC port PID Command line Working directory + ------------ ------------- -------- ----------- ----- ------------------------------------------------------------------------- -------------------------------- + ANSYS False running 50052 35360 /ansys_inc/v222/ansys/bin/linx64/ansys -j file -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp + ANSYS False running 50052 37116 /ansys_inc/v222/ansys/bin/linx64/ansys -j file -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp + ANSYS222 True running 50052 41644 /ansys_inc/v222/ansys/bin/linx64/ansys222 -j file -np 2 -port 50052 -grpc /home/user/temp/ansys_ahmfaliakp + + +The converter module has its own command line interface to convert +MAPDL files to PyMAPDL. For more information, see +:ref:`ref_cli_converter`. \ No newline at end of file diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 5936e3dbd9..5eb934e06a 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -11,6 +11,7 @@ contribution faq versioning + cli docker macos wsl diff --git a/doc/source/getting_started/launcher.rst b/doc/source/getting_started/launcher.rst index df173b2433..0d8ae78403 100644 --- a/doc/source/getting_started/launcher.rst +++ b/doc/source/getting_started/launcher.rst @@ -90,6 +90,9 @@ port 50005 with this command: /usr/ansys_inc/v241/ansys/bin/ansys211 -port 50005 -grpc +From version v0.68, you can use a command line interface to launch, stop and list +local MAPDL instances. +For more information, see :ref:`ref_cli`. .. _connect_grpc_madpl_session: diff --git a/doc/source/user_guide/convert.rst b/doc/source/user_guide/convert.rst index d7d34a050e..b0155e2924 100644 --- a/doc/source/user_guide/convert.rst +++ b/doc/source/user_guide/convert.rst @@ -8,6 +8,8 @@ would take place within Python because APDL commands are less transparent and more difficult to debug. +.. _ref_cli_converter: + Command-line interface ----------------------