launch_mapdl#

ansys.mapdl.core.launcher.launch_mapdl(exec_file=None, run_location=None, jobname='file', *, nproc=None, port=None, ip=None, channel=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 or connect to existing instance.

This is the main entry point for all MAPDL launching operations. It uses the domain-driven modular architecture while maintaining 100% backward compatibility with the legacy launcher API.

When start_instance=True (the default), this function launches a new MAPDL instance and returns a client for interacting with it. When start_instance=False, this function connects to an existing MAPDL instance running at the specified ip and port.

パラメーター:
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. The temporary directory is removed when MAPDL exits if cleanup_on_exit is True.

jobnamestr

MAPDL jobname. Defaults to 'file'.

nprocOptional[int]

Number of processors. If running on an HPC cluster, this value is adjusted to the number of CPUs allocated to the job, unless running_on_hpc=False. Defaults to 2 CPUs.

portOptional[int]

Port to launch MAPDL gRPC on. Can also be set via environment variable PYMAPDL_PORT. Argument has precedence. Defaults to 50052.

ipOptional[str]

IP address of MAPDL instance. Used only when start_instance=False. Can also be set via environment variable PYMAPDL_IP. Defaults to '127.0.0.1' (localhost).

channelOptional[Any]

Communication channel to use. It cannot be used with ip and port arguments.

modeOptional[str]

Launch mode. Must be one of:

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

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

The gRPC mode provides the best performance and stability.

versionOptional[int]

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

start_instanceOptional[bool]

When False, connect to existing MAPDL at ip and port. When True, launch a new MAPDL instance locally. Can also be set via environment variable PYMAPDL_START_INSTANCE. Defaults to start locally (True).

ramOptional[int]

Total workspace (memory) in megabytes for initial allocation. Specify a negative number to force a fixed size throughout the run. Defaults to None (2048 MB).

timeoutOptional[int]

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

cleanup_on_exitbool

Exit MAPDL when Python exits or MAPDL instance is garbage collected. Defaults to True.

clear_on_connectbool

Provide a fresh environment when connecting to MAPDL. Defaults to True.

overridebool

Delete the lock file at run_location if it exists. Useful when a prior session exited prematurely. Defaults to False.

remove_temp_dir_on_exitbool

Delete temporary directory created for MAPDL launch when exiting. Defaults to False. Note: Not available on HPC.

set_no_abortbool

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

additional_switchesstr

Additional MAPDL command-line switches. For example, '-aa_r' for academic research license. Avoid switches like -i, -o, -b as they are already set. Common switches include:

  • '-smp' - Shared-memory parallelism

  • '-dmp' - Distributed-memory parallelism

  • '-mpi intelmpi' - Specify Intel MPI

  • '-mpi msmpi' - Specify Microsoft MPI

  • '-acc gpu' - GPU acceleration

  • '-amfg' - Additive manufacturing capability

Defaults to empty string.

license_typeOptional[str]

License type to request. Can be a license name (e.g., 'meba', 'ansys') or description (e.g., "enterprise solver"). Legacy licenses (e.g., 'aa_t_a') are supported but may raise warnings. Defaults to None (server decides).

launch_on_hpcbool

Launch on HPC cluster using SLURM scheduler (SLURM only). Pass scheduler_options to specify scheduler arguments. Defaults to False.

running_on_hpcbool

Whether to detect if PyMAPDL is running on an HPC cluster. Currently only SLURM is supported. Can be overridden via PYMAPDL_RUNNING_ON_HPC. Defaults to False.

scheduler_optionsOptional[Dict[str, Any]]

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

loglevelstr

PyMAPDL logging level. Options:

  • 'DEBUG' - All logs

  • 'INFO' - Informational

  • 'WARNING' - Warnings only

  • 'ERROR' - Errors only

Defaults to 'ERROR'.

log_apdlOptional[str]

Log APDL commands to file. Path to output file (e.g., 'pymapdl_log.txt') or True to use 'apdl.log'. Useful for recording commands to replay in MAPDL without PyMAPDL. Defaults to None (disabled).

print_combool

Print /COM command arguments to console output. Defaults to False.

mapdl_outputOptional[str]

Redirect MAPDL console output to file. Useful for debugging. Overwritten if file exists. Can include path. Defaults to None (not redirected).

transport_modeOptional[str]

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

uds_dirOptional[str]

Directory for Unix Domain Socket (UDS) files with 'uds' transport. Defaults to None (uses ~/.conn).

uds_idOptional[str]

Identifier for UDS socket file with 'uds' transport. Defaults to None (uses mapdl-{port}).

certs_dirOptional[str]

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

add_env_varsOptional[Dict[str, str]]

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

replace_env_varsOptional[Dict[str, str]]

Environment variables to replace system ones.

警告

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

Defaults to None (uses system environment).

license_server_checkbool

Check if license server is available if MAPDL fails to start. Only on mode='grpc'. Defaults to False.

force_intelbool

Force Intel MPI in ANSYS versions 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. Maintained for backward compatibility, will be removed in future version.

**kwargsAny

Additional arguments. Unknown arguments generate warnings.

Returns:
Union[MapdlGrpc, MapdlConsole]

MAPDL client instance for interaction. Type depends on mode.

Raises:
ConfigurationError

Invalid configuration or conflicting settings.

LaunchError

Launch failed or MAPDL failed to start.

ConnectionError

Cannot connect to existing MAPDL instance.

戻り値の型:

Union[MapdlGrpc, MapdlConsole]

Notes

Ansys Student Version

If an Ansys Student version is detected, PyMAPDL automatically launches MAPDL in shared-memory parallelism (SMP) mode unless another option is specified.

Additional Switches

Commonly used MAPDL switches (as of ANSYS 2020R2+):

-acc <device>

Enable GPU hardware acceleration. See GPU Accelerator Capability in the Parallel Processing Guide.

-amfg

Enable additive manufacturing. Requires appropriate license.

-ansexe <executable>

Activate a custom mechanical APDL executable.

-db value

Initial memory allocation. Default is 1024 MB. Negative number forces fixed size throughout run.

-dis

Enable Distributed ANSYS. See Parallel Processing Guide.

-dvt

Enable ANSYS DesignXplorer advanced task (requires DesignXplorer).

-l <language>

Specify language file for non-English localization.

-m <workspace>

Total workspace size in MB. Default is 2048 MB. Negative number forces fixed size throughout run.

-machines <IP>

Distributed machines for Distributed ANSYS analysis.

-mpi <value>

MPI type: intelmpi, msmpi, openmpi, etc.

-mpifile <appfile>

Existing MPI file for Distributed ANSYS.

-na <value>

Number of GPU accelerator devices per machine/node.

-name <value>

Define APDL parameters at startup.

-p <productname>

ANSYS session product (e.g., 'meba', 'ansys').

-ppf <license_feature>

HPC license feature. See HPC Licensing in Parallel Processing Guide.

-smp

Enable shared-memory parallelism.

PyPIM Integration

If the environment is configured for PyPIM and start_instance=True, MAPDL startup is delegated to PyPIM and most launch options are ignored.

Architecture

This implementation uses the domain-driven modular architecture:

  • Configuration resolution (config.resolve_launch_config())

  • Validation (validation.validate_config())

  • Environment setup (environment.prepare_environment())

  • Process launching:

    • Local: process.launch_mapdl_process()

    • HPC: hpc.launch_on_hpc()

  • Client creation:

    • gRPC: connection.create_grpc_client()

    • Console: connection.create_console_client()

Examples

Launch MAPDL using recommended settings:

>>> from ansys.mapdl.core import launch_mapdl
>>> mapdl = launch_mapdl()

Launch with specific version and processor count:

>>> mapdl = launch_mapdl(version=222, nproc=4)

Run with shared-memory parallelism at specific location:

>>> exec_file = 'C:/Program Files/ANSYS Inc/v252/ansys/bin/winx64/ANSYS252.exe'
>>> mapdl = launch_mapdl(
...     exec_file=exec_file,
...     additional_switches='-smp'
... )

Connect to an existing MAPDL instance:

>>> mapdl = launch_mapdl(
...     start_instance=False,
...     ip='192.168.1.30',
...     port=50001
... )

Run MAPDL in console mode (Linux only, not recommended):

>>> mapdl = launch_mapdl(
...     '/ansys_inc/v194/ansys/bin/ansys194',
...     mode='console'
... )

Launch with custom environment variables:

>>> my_env = {"MY_VAR": "true", "ANSYS_LOCK": "FALSE"}
>>> mapdl = launch_mapdl(add_env_vars=my_env)

Launch on HPC with SLURM options:

>>> mapdl = launch_mapdl(
...     launch_on_hpc=True,
...     nproc=16,
...     scheduler_options={'nodes': '2', 'ntasks-per-node': '8'}
... )