refactor: launcher according to modules

.github/dependabot.yml

@@ -55,7 +55,7 @@ updates:
       exclude:
         - "ansys-tools-visualization-interface"
     exclude-paths:
-      - "/doc/source/examples/extended_examples/**"
+      - "doc/source/examples/extended_examples/**"
     groups:
        minimal:
           patterns:

.github/workflows/test-remote.yml

@@ -93,7 +93,7 @@ jobs:
       PYANSYS_OFF_SCREEN: True
       PYMAPDL_DB_PORT: 21002  # default won't work on GitHub runners
       PYMAPDL_DB_PORT2: 21003  # default won't work on GitHub runners
-      PYMAPDL_DEBUG_TESTING: True
+      PYMAPDL_DEBUG_TESTING: False
       PYMAPDL_GRPC_TRANSPORT: 'insecure'
       PYMAPDL_PORT: 21000  # default won't work on GitHub runners
       PYMAPDL_PORT2: 21001  # for the pool testing and default won't work on GitHub runners

doc/changelog.d/4416.miscellaneous.md

@@ -0,0 +1 @@
+Launcher according to modules

doc/source/api/launcher.rst

@@ -15,6 +15,7 @@ library `ansys-tools-common.path <ansys_tools_common_>`_.
    get_default_ansys_path
    get_default_ansys_version
    launch_mapdl
+   launch_mapdl_process
    close_all_local_instances
 
 

doc/source/getting_started/launcher.rst

@@ -42,6 +42,43 @@
 description of the :func:`launch_mapdl() <ansys.mapdl.core.launcher.launch_mapdl>` function.
 
 
+Launch MAPDL process without creating a client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you may want to launch a MAPDL process without immediately creating a
+client connection. This is useful for:
+
+* Starting MAPDL from the command-line interface (CLI)
+* Managing multiple MAPDL instances programmatically
+* Launching MAPDL in a separate process for later connection
+
+For these scenarios, you can use the :func:`launch_mapdl_process() <ansys.mapdl.core.launcher.launch_mapdl_process>`
+function, which starts MAPDL and returns connection information without creating a client:
+
+.. code:: pycon
+
+    >>> from ansys.mapdl.core.launcher import launch_mapdl_process
+    >>> ip, port, pid = launch_mapdl_process(nproc=4, port=50052)
+    >>> print(f"MAPDL is running at {ip}:{port} (PID: {pid})")
+    MAPDL is running at 127.0.0.1:50052 (PID: 12345)
+
+You can later connect to this instance using the :class:`Mapdl <ansys.mapdl.core.Mapdl>` class:
+
+.. code:: pycon
+
+    >>> from ansys.mapdl.core import Mapdl
+    >>> mapdl = Mapdl(ip=ip, port=port)
+
+This approach gives you more control over the MAPDL process lifecycle and allows
+you to manage the process independently from the client connection.
+
+.. note::
+   The :func:`launch_mapdl_process() <ansys.mapdl.core.launcher.launch_mapdl_process>`
+   function always starts a new MAPDL instance. It cannot be used to connect to
+   an existing instance. Use :func:`launch_mapdl() <ansys.mapdl.core.launcher.launch_mapdl>`
+   with ``start_instance=False`` for that purpose.
+
+
 Connect PyMAPDL to a local MAPDL instance
 -----------------------------------------
 

doc/source/user_guide/cli.rst

@@ -56,10 +56,13 @@ If you want to specify an argument, for instance the port, then you need to call
             Success: Launched an MAPDL instance (PID=18238) at 127.0.0.1:50054
 
 
-This ``pymapdl start`` command 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:
+This ``pymapdl start`` command uses the
+:func:`ansys.mapdl.core.launcher.launch_mapdl_process` function internally
+to start MAPDL without creating a client connection. The command returns the
+connection information (IP, port, and PID) that you can use to connect later.
+
+Some of the arguments that :func:`ansys.mapdl.core.launcher.launch_mapdl` allows
+are also available in the CLI. For instance, you could specify the working directory:
 
 .. tab-set::
 
@@ -80,7 +83,8 @@ For instance, you could specify the working directory:
             Success: Launched an MAPDL instance (PID=32612) at 127.0.0.1:50052
 
 
-For more information, see :func:`ansys.mapdl.core.launcher.launch_mapdl`.
+For more information about the underlying function, see
+:func:`ansys.mapdl.core.launcher.launch_mapdl_process`.
 
 
 Stop MAPDL instances

pyproject.toml

@@ -140,7 +140,7 @@ addopts = [
   "--durations=30",
   "--log-file-level=DEBUG",
   "--log-file=pytest.log",
-  "--maxfail=2",
+  "--maxfail=2000",
   "--profile",
   "--profile-svg",
   "--random-order",

src/ansys/mapdl/core/_numpy_compat.py

@@ -27,7 +27,7 @@
 removed or deprecated in newer versions.
 
 NumPy 2.0+ Compatibility
-=========================
+========================
 
 NumPy removed in1d in version 2.0 (replaced by numpy.isin), but some of our
 dependencies may still reference it, causing AttributeError on import.

src/ansys/mapdl/core/cli/start.py

@@ -192,102 +192,113 @@ def start(
     replace_env_vars: Dict[str, str],  # ignored
     version: Union[int, str],
 ) -> None:
-    from ansys.mapdl.core.launcher import launch_mapdl
+    import logging
 
-    if mode:
-        click.echo(
-            click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'mode'.\nIgnoring argument."
-        )
+    from ansys.mapdl.core.launcher import launch_mapdl_process
 
-    if loglevel:
+    if mode is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'loglevel'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'mode'. Ignoring argument."
         )
 
-    if cleanup_on_exit:
+    if cleanup_on_exit is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'cleanup_on_exit'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'cleanup_on_exit'. Ignoring argument."
         )
 
-    if start_instance:
+    if start_instance is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'start_instance'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'start_instance'. Ignoring argument."
         )
 
-    if ip:
+    if ip is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'ip'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'ip'. Ignoring argument."
         )
 
-    if clear_on_connect:
+    if clear_on_connect is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'clear_on_connect'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'clear_on_connect'. Ignoring argument."
         )
 
-    if log_apdl:
+    if log_apdl is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'log_apdl'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'log_apdl'. Ignoring argument."
         )
 
-    if remove_temp_dir_on_exit:
+    if remove_temp_dir_on_exit is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'remove_temp_dir_on_exit'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'remove_temp_dir_on_exit'. Ignoring argument."
         )
 
-    if print_com:
+    if print_com is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'print_com'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'print_com'. Ignoring argument."
         )
 
-    if add_env_vars:
+    if add_env_vars is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'add_env_vars'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'add_env_vars'. Ignoring argument."
         )
 
-    if replace_env_vars:
+    if replace_env_vars is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'replace_env_vars'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'replace_env_vars'. Ignoring argument."
         )
 
-    if license_server_check:
+    if license_server_check is not None:
         click.echo(
             click.style("Warn:", fg="yellow")
-            + " The following argument is not allowed in CLI: 'license_server_check'.\nIgnoring argument."
+            + " The following argument is not allowed in CLI: 'license_server_check'. Ignoring argument."
         )
 
     # Ignoring env var if using CLI
     if "PYMAPDL_START_INSTANCE" in os.environ:
         os.environ.pop("PYMAPDL_START_INSTANCE")
 
-    out = launch_mapdl(
-        exec_file=exec_file,
-        just_launch=True,
-        run_location=run_location,
-        jobname=jobname,
-        nproc=nproc,
-        ram=ram,
-        override=override,
-        additional_switches=additional_switches,
-        start_timeout=start_timeout,
-        port=port,
-        license_type=license_type,
-        version=version,
-    )
+    # Suppress all logging to stdout when using CLI
+    from ansys.mapdl.core import LOG
+
+    if not loglevel:
+        LOG.setLevel(
+            logging.CRITICAL + 1
+        )  # Set to a level higher than CRITICAL to suppress all logs
+        if LOG.std_out_handler:
+            LOG.std_out_handler.setLevel(logging.CRITICAL + 1)
+
+    try:
+        ip_addr, port_num, pid = launch_mapdl_process(
+            exec_file=exec_file,
+            run_location=run_location,
+            jobname=jobname,
+            nproc=nproc,
+            ram=ram,
+            override=override,
+            additional_switches=additional_switches,
+            start_timeout=start_timeout,
+            port=port,
+            license_type=license_type,
+            version=version,
+            loglevel=loglevel,  # Set to highest level to suppress all logging
+        )
+
+    except Exception as e:
+        click.echo(click.style("ERROR:", fg="red") + f" {e}")
+        exit(1)
 
-    if len(out) == 3:
-        header = f"Launched an MAPDL instance (PID={out[2]}) at "
+    if pid is not None:
+        header = f"Launched an MAPDL instance (PID={pid}) at "
     else:
         header = "Launched an MAPDL instance at "
 
-    click.echo(click.style("Success: ", fg="green") + header + f"{out[0]}:{out[1]}")
+    click.echo(click.style("Success: ", fg="green") + header + f"{ip_addr}:{port_num}")