Adding entry point to launch_mapdl

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`.

doc/source/getting_started/index.rst

@@ -12,6 +12,7 @@
    codespaces
    faq
    versioning
+   cli
    docker
    macos
    wsl

doc/source/getting_started/launcher.rst

@@ -90,6 +90,9 @@
 
     /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:
 

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
 ----------------------
 

pyproject.toml

@@ -23,6 +23,7 @@ dependencies = [
     "ansys-platform-instancemanagement~=1.0",
     "platformdirs>=3.6.0",
     "click>=8.1.3", # for CLI interface
+    "tabulate>=0.8.0", # for cli plotting
     "grpcio>=1.30.0",  # tested up to grpcio==1.35
     "importlib-metadata>=4.0",
     "matplotlib>=3.0.0",  # for colormaps for pyvista
@@ -112,7 +113,8 @@ name = "ansys.mapdl.core"
 Source = "https://github.com/ansys/pymapdl"
 
 [project.scripts]
-pymapdl_convert_script = "ansys.mapdl.core.convert:cli"
+pymapdl_convert_script = "ansys.mapdl.core.cli:convert"
+launch_mapdl = "ansys.mapdl.core.cli:launch_mapdl"
 
 [tool.pytest.ini_options]
 junit_family = "legacy"