launch_mapdl_process#

ansys.mapdl.core.launcher.launch_mapdl_process(exec_file=None, run_location=None, jobname='file', *, nproc=None, port=None, ip=None, mode=None, version=None, start_instance=None, ram=None, timeout=None, cleanup_on_exit=True, clear_on_connect=True, override=False, remove_temp_dir_on_exit=False, set_no_abort=True, additional_switches='', license_type=None, launch_on_hpc=False, running_on_hpc=False, scheduler_options=None, loglevel='ERROR', log_apdl=None, print_com=False, mapdl_output=None, transport_mode=None, uds_dir=None, uds_id=None, certs_dir=None, add_env_vars=None, replace_env_vars=None, license_server_check=False, force_intel=False, graphics_backend=None, start_timeout=None, **kwargs)#

Launch MAPDL process and return connection info without creating client.

This is the specialized entry point for CLI and programmatic use cases that need the process to be launched without immediately creating a client connection. Unlike launch_mapdl(), this function: :rtype: tuple[str, int, Optional[int]]

  • Does NOT connect to an existing instance

  • Returns connection info tuple (ip, port, pid) instead of a client

  • Does NOT create a client object

  • Requires start_instance=True

This function is primarily used by the CLI to launch MAPDL without creating a client connection. The caller is responsible for managing the launched process lifecycle.

Parameters:
exec_fileOptional[str]

The location of the MAPDL executable. For instance, on Windows:

  • C:\Program Files\ANSYS Inc\v252\ansys\bin\mapdl.exe

And on Linux:

  • /usr/ansys_inc/v252/ansys/bin/mapdl

By default (None), uses the cached location unless the environment variable PYMAPDL_MAPDL_EXEC is set.

run_locationOptional[str]

MAPDL working directory. If the directory doesn’t exist, one is created. Defaults to a temporary working directory with name 'ansys_' and a random string.

jobnamestr

MAPDL jobname. Defaults to 'file'.

nprocOptional[int]

Number of processors. If running on an HPC cluster, adjusted to allocated CPUs unless running_on_hpc=False. Defaults to 2 CPUs.

portOptional[int]

Port for MAPDL gRPC. Can be set via PYMAPDL_PORT. Argument has precedence. Defaults to 50052.

ipOptional[str]

IP address to bind MAPDL to. For HPC, typically left empty. Defaults to '127.0.0.1'.

modeOptional[str]

Launch mode. Options:

  • 'grpc' - Recommended for ANSYS 2021R1 or newer

  • 'console' - Legacy console mode, Linux only (not recommended)

This parameter is largely ignored as gRPC is enforced.

versionOptional[int]

MAPDL version to launch. Can be provided as integers (version=222) or floats (version=22.2). Can be set via environment variable PYMAPDL_MAPDL_VERSION. Defaults to latest installed version.

start_instanceOptional[bool]

MUST be :class:`True` for this function. This function always requires launching a new instance. Can be set via environment variable PYMAPDL_START_INSTANCE. Defaults to True.

ramOptional[int]

Total workspace (memory) in megabytes. Negative number forces fixed size. Defaults to None (2048 MB).

timeoutOptional[int]

Maximum time to connect to MAPDL server in seconds. Defaults to 45 seconds (90 seconds on HPC).

cleanup_on_exitbool

Exit MAPDL when Python exits. Defaults to True.

clear_on_connectbool

Provide fresh environment when connecting. Defaults to True.

overridebool

Delete lock file at run_location if it exists. Defaults to False.

remove_temp_dir_on_exitbool

Delete temporary directory when exiting. Defaults to False. Not available on HPC.

set_no_abortbool

Do not abort at first error in /BATCH mode. (Development use only). Defaults to True.

additional_switchesstr

Additional MAPDL command-line switches. Avoid -i, -o, -b. Examples: '-smp', '-dmp', '-mpi intelmpi'. Defaults to empty string.

license_typeOptional[str]

License type to request (e.g., 'meba', 'ansys'). Defaults to None (server decides).

launch_on_hpcbool

Launch on HPC cluster using SLURM scheduler. Defaults to False.

running_on_hpcbool

Whether to detect if running on HPC cluster. Can override with PYMAPDL_RUNNING_ON_HPC. Defaults to False.

scheduler_optionsOptional[Dict[str, Any]]

HPC scheduler options. Example: {"nodes": "2", "ntasks-per-node": "8"}

loglevelstr

PyMAPDL logging level: 'DEBUG', 'INFO', 'WARNING', 'ERROR'. Defaults to 'ERROR'.

log_apdlOptional[str]

Log APDL commands to file. Path or True for 'apdl.log'. Defaults to None (disabled).

print_combool

Print /COM command arguments. Defaults to False.

mapdl_outputOptional[str]

Redirect MAPDL console output to file. Useful for debugging. Defaults to None (not redirected).

transport_modeOptional[str]

gRPC transport mode: 'insecure', 'uds', 'wnua', 'mtls'. Defaults to None (auto-select).

uds_dirOptional[str]

Directory for Unix Domain Socket (UDS) files. Defaults to None (~/.conn).

uds_idOptional[str]

Identifier for UDS socket file. Defaults to None (mapdl-{port}).

certs_dirOptional[str]

Directory with certificates for 'mtls' transport. Defaults to None.

add_env_varsOptional[Dict[str, str]]

Environment variables to add. Extends system environment. Defaults to None.

replace_env_varsOptional[Dict[str, str]]

Environment variables to replace system ones.

Warning

Use with caution. Replaces ALL system environment variables including MPI and license-related ones. Manually inject if needed.

Defaults to None (uses system environment).

license_server_checkbool

Check license server availability on MAPDL startup failure. Only on mode='grpc'. Defaults to False.

force_intelbool

Force Intel MPI for ANSYS 2021R0-2022R2. (Development use only). Defaults to False.

graphics_backendOptional[str]

Graphics backend to use. Defaults to None.

start_timeoutOptional[int]

Deprecated. Use ``timeout`` instead.

**kwargsAny

Additional arguments. Unknown arguments generate warnings.

Returns:
tuple[str, int, Optional[int]]

Tuple of (ip, port, pid) for the launched MAPDL instance:

  • ip - IP address where MAPDL is listening

  • port - gRPC port number

  • pid - Process ID (or None for remote/HPC launches)

Raises:
ConfigurationError

Invalid configuration or conflicting settings.

LaunchError

Launch failed or MAPDL failed to start.

Notes

This function is primarily used by the CLI to launch MAPDL without creating a client connection. The caller is responsible for:

  • Managing the launched process

  • Creating a client connection if needed

  • Cleaning up resources

For most use cases, launch_mapdl() is recommended as it automatically creates and manages the client connection.

Example CLI workflow:

>>> ip, port, pid = launch_mapdl_process(nproc=8)
>>> # Pass connection info to other processes or store it
>>> # When ready to connect:
>>> from ansys.mapdl.core import launch_mapdl
>>> mapdl = launch_mapdl(start_instance=False, ip=ip, port=port)

Examples

Launch MAPDL process and get connection info:

>>> from ansys.mapdl.core.launcher import launch_mapdl_process
>>> ip, port, pid = launch_mapdl_process(nproc=4)
>>> print(f"MAPDL listening at {ip}:{port} (PID: {pid})")
MAPDL listening at 127.0.0.1:50052 (PID: 12345)

Use with specific version and switches:

>>> ip, port, pid = launch_mapdl_process(
...     version=222,
...     nproc=4,
...     additional_switches='-smp'
... )

Launch on HPC and get connection info:

>>> ip, port, pid = launch_mapdl_process(
...     launch_on_hpc=True,
...     nproc=16,
...     scheduler_options={'nodes': '2', 'ntasks-per-node': '8'}
... )