launch_mapdl#

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

Start MAPDL locally.

Parameters:

exec_filestr, optional

The location of the MAPDL executable. By default (None), it Will use the cached location unless the environment variable PYMAPDL_MAPDL_EXEC is set.

export PYMAPDL_MAPDL_EXEC=/ansys_inc/v211/ansys/bin/mapdl

run_locationstr, optional

MAPDL working directory. If directory doesn’t exist, one is created. Defaults to a temporary working directory created in the directory obtained by tempfile.gettempdir() and starting with name 'ansys_' and a random string. The temporary directory is removed when MAPDL exits if cleanup_on_exit is True.

jobnamestr, optional

MAPDL jobname. Defaults to 'file'.

add_env_varsdict, optional

The provided dictionary will be used to extend the MAPDL process environment variables. If you want to control all of the environment variables, use the argument replace_env_vars to inject only some specific environment variables. Defaults to None, which means no additional environment variables are set.

additional_switchesstr, optional

Additional switches for MAPDL, for example 'aa_r', the academic research license, would be added with:

additional_switches="-aa_r"

Avoid adding switches like -i, -o or -b as these are already included to start up the MAPDL server. See the notes section for additional details. Defaults to None, which means no additional switches are added.

cleanup_on_exitbool, optional

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

clear_on_connectbool, optional

Defaults to True, giving you a fresh environment when connecting to MAPDL. When if start_instance is specified it defaults to False, otherwise it defaults to True.

ipstr, optional

Specify the IP address of the MAPDL instance to connect to. You can also provide a hostname as an alternative to an IP address. Used only when start_instance is False. If this argument is provided, and start_instance (or its correspondent environment variable PYMAPDL_START_INSTANCE) is True then, an exception is raised. You can also provide this value through the environment variable PYMAPDL_IP. For instance PYMAPDL_IP=123.45.67.89. However the argument (if specified) has precedence over the environment variable. If this environment variable is empty, it is as it is not set. Defaults to '127.0.0.1' (connect to a local instance).

launch_on_hpcbool, Optional

If True, it uses the implemented scheduler (SLURM only) to launch an MAPDL instance on the HPC. In this case you can pass the ‘scheduler_options’ argument to launch_mapdl() to specify the scheduler arguments as a string or as a dictionary. If False, these scheduler options are ignored. For more information, see Introduction to SLURM. Defaults to False.

license_server_checkbool, optional

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

license_typestr, optional

Enable license type selection. You can input a string for its license name (for example 'meba' or 'ansys') or its description (“enterprise solver” or “enterprise” respectively). You can also use legacy licenses (for example 'aa_t_a') but it will also raise a warning. By default, it is not especified (None), which means that no specific license will be requested, being up to the license server to provide a specific license.

log_apdlstr, optional

Enables logging every APDL command to a file. This can be used to “record” all the commands that are sent to MAPDL via PyMAPDL so a script can be run within MAPDL without PyMAPDL. This argument is the path of the output file (e.g. log_apdl='pymapdl_log.txt'), or a boolean value. If it is True, the file will be created in the current working directory with the name "apdl.log". By default this is disabled, log_apdl is None.

loglevelstr, optional

Sets which messages from the PyMAPDL Logger are printed to the console. 'DEBUG' prints out all the PyMAPDL logs, 'INFO' prints out only informational messages, 'WARNING' prints only messages containing ANSYS warnings, and 'ERROR' logs only error messages. Defaults to 'ERROR', only error messages are printed to the console.

mapdl_outputstr, optional

Redirect the MAPDL console output to a file. This is useful to check the MAPDL output in case of errors. The file is created in the working directory unless the path is included in the filename. If the file already exists, it will be overwritten. For example, mapdl_output='my/path/to/my_mapdl_output.txt'. Defaults to None, in which case the output is not redirected.

modestr, optional

Mode to launch MAPDL. Must be one of the following:

'grpc'
'console'

The 'grpc' mode is available on ANSYS 2021R1 or newer and provides the best performance and stability. This is the recommended mode to interact with MAPDL. The 'console' mode is for legacy use (before ANSYS MAPDL 2020R2) and only can be used on Linux. This console mode is not recommended. Visit Versions and interfaces for more information.

nprocint, optional

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

overridebool, optional

Attempts to delete the lock file at the run_location. Useful when a prior MAPDL session has exited prematurely and the lock file has not been deleted. Defaults to False, which means that the lock file is not deleted.

portint

Port to launch MAPDL gRPC on. You can also provide this value through the environment variable PYMAPDL_PORT.

export PYMAPDL_PORT=50053

However the argument (if specified) has precedence over the environment variable. If this environment variable is empty, it is as it is not set. Defaults to 50052.

print_combool, optional

Print the command /COM arguments to the standard output. Defaults to False.

ramfloat, optional

Total size in megabytes of the workspace (memory) used for the initial allocation. To force a fixed size throughout the run, specify a negative number. The default is None, in which case 2 GB (2048 MB) is used.

remove_temp_dir_on_exitbool, optional

When this parameter is True, the directory created to launch MAPDL on temporary location will be deleted when MAPDL is exited. If you change the working directory, PyMAPDL does not delete the original working directory nor the new one. Defaults to False.

Note

This option is not available when running on HPC.

replace_env_varsdict, optional

The provided dictionary will be used to replace all the MAPDL process environment variables with the values in the dictionary.

Warning

Use with caution. It also replaces all the system environment variables, for instance MPI and license related environment variables. You should take care of inject them manually using this argument.

To just add some environment variables to the MAPDL process, use add_env_vars argument. Defaults to None which means no environment variables are replaced.

running_on_hpc: bool, optional

Whether detect if PyMAPDL is running on an HPC cluster. Currently only SLURM clusters are supported. This option can be bypassed if the PYMAPDL_RUNNING_ON_HPC environment variable is set to True.

export PYMAPDL_RUNNING_ON_HPC=true

For more information, see Introduction to SLURM. Defaults to True.

start_instancebool, optional

When False, connect to an existing MAPDL instance at ip and port, which default to ip '127.0.0.1' at port 50052. Otherwise, launch a local instance of MAPDL. You can also provide this value through the environment variable PYMAPDL_START_INSTANCE.

export PYMAPDL_START_INSTANCE=false

However the argument (if specified) has precedence over the environment variable. If this environment variable is empty, it is as it is not set. Defaults to start locally (True).

start_timeoutfloat, optional

Maximum allowable time to connect to the MAPDL server. By default it is 45 seconds, however, it is increased to 90 seconds if running on HPC.

versionfloat, optional

Version of MAPDL to launch. Versions can be provided as integers (i.e. version=222) or floats (i.e. version=22.2). To retrieve the available installed versions, use the function ansys.tools.path.get_available_ansys_installations(). You can also provide this value through the environment variable PYMAPDL_MAPDL_VERSION. For instance:

export PYMAPDL_MAPDL_VERSION=22.2

However the argument (if specified) has precedence over the environment variable. If this environment variable is empty, it is as it is not set. Defaults to latest available version (None).

kwargsdict, Optional

These keyword arguments are interface-specific or for development purposes. For more information, see Notes.

scheduler_optionsstr, dict: Use it to specify options to the scheduler run command. It can be a string or a dictionary with arguments and its values (both as strings). For more information visit Introduction to SLURM.
set_no_abortbool: (Development use only) Sets MAPDL to not abort at the first error within /BATCH mode. Defaults to True.
force_intelbool: (Development use only) Forces the use of Intel message pass interface (MPI) in versions between Ansys 2021R0 and 2022R2, where because of VPNs issues this MPI is deactivated by default. See Virtual private network (VPN) issues for more information. Defaults to False.

Returns:

Union[MapdlGrpc, MapdlConsole]: An instance of Mapdl. Type depends on the selected mode.

Return type:

Union[MapdlGrpc, MapdlConsole]

Notes

Ansys Student Version

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

Additional switches

These are the MAPDL switch options as of 2020R2 applicable for running MAPDL as a service via gRPC. Excluded switches not applicable or are set via keyword arguments such as "-j" .

-acc <device>: Enables the use of GPU hardware. See GPU Accelerator Capability in the Parallel Processing Guide for more information.
-amfg: Enables the additive manufacturing capability. Requires an additive manufacturing license. For general information about this feature, see AM Process Simulation in ANSYS Workbench.
-ansexe <executable>: Activates a custom mechanical APDL executable. In the ANSYS Workbench environment, activates a custom Mechanical APDL executable.
-custom <executable>: Calls a custom Mechanical APDL executable See Running Your Custom Executable in the Programmer’s Reference for more information.
-db value: Initial memory allocation Defines the portion of workspace (memory) to be used as the initial allocation for the database. The default is 1024 MB. Specify a negative number to force a fixed size throughout the run; useful on small memory systems.
-dis: Enables Distributed ANSYS See the Parallel Processing Guide for more information.
-dvt: Enables ANSYS DesignXplorer advanced task (add-on). Requires DesignXplorer.
-l <language>: Specifies a language file to use other than English This option is valid only if you have a translated message file in an appropriately named subdirectory in /ansys_inc/v201/ansys/docu or Program Files\ANSYS\Inc\V201\ANSYS\docu
-m <workspace>: Specifies the total size of the workspace Workspace (memory) in megabytes used for the initial allocation. If you omit the -m option, the default is 2 GB (2048 MB). Specify a negative number to force a fixed size throughout the run.
-machines <IP>: Specifies the distributed machines Machines on which to run a Distributed ANSYS analysis. See Starting Distributed ANSYS in the Parallel Processing Guide for more information.
-mpi <value>: Specifies the type of MPI to use. See the Parallel Processing Guide for more information.
-mpifile <appfile>: Specifies an existing MPI file Specifies an existing MPI file (appfile) to be used in a Distributed ANSYS run. See Using MPI Files in the Parallel Processing Guide for more information.
-na <value>: Specifies the number of GPU accelerator devices Number of GPU devices per machine or compute node when running with the GPU accelerator feature. See GPU Accelerator Capability in the Parallel Processing Guide for more information.
-name <value>: Defines Mechanical APDL parameters Set mechanical APDL parameters at program start-up. The parameter name must be at least two characters long. For details about parameters, see the ANSYS Parametric Design Language Guide.
-p <productname>: ANSYS session product Defines the ANSYS session product that will run during the session. For more detailed information about the -p option, see Selecting an ANSYS Product via the Command Line.
-ppf <license feature name>: HPC license Specifies which HPC license to use during a parallel processing run. See HPC Licensing in the Parallel Processing Guide for more information.
-smp: Enables shared-memory parallelism. See the Parallel Processing Guide for more information.

PyPIM

If the environment is configured to use PyPIM and start_instance is True, then starting the instance will be delegated to PyPIM. In this event, most of the options will be ignored and the server side configuration will be used.

Examples

Launch MAPDL using the best protocol.

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

Run MAPDL with shared memory parallel and specify the location of the Ansys binary.

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

Connect to an existing instance of MAPDL at IP 192.168.1.30 and port 50001. This is only available using the latest 'grpc' mode.

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

Run MAPDL using the console mode (not recommended, and available only on Linux).

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

Run MAPDL with additional environment variables.

>>> my_env_vars = {"my_var":"true", "ANSYS_LOCK":"FALSE"}
>>> mapdl = launch_mapdl(add_env_vars=my_env_vars)

Run MAPDL with our own set of environment variables. It replace the system environment variables which otherwise would be used in the process.

>>> my_env_vars = {"my_var":"true",
    "ANSYS_LOCK":"FALSE",
    "ANSYSLMD_LICENSE_FILE":"1055@MYSERVER"}
>>> mapdl = launch_mapdl(replace_env_vars=my_env_vars)