Troubleshooting PyMAPDL#

This page covers common problems and frequently asked questions that you might encounter when using PyMAPDL.

Debug PyMAPDL#

If you are having trouble with PyMAPDL, you can record internal logs to a file using a logger. Examine this file to identify issues.

Also, set the run_location argument to a known location, such as the current directory, so that you can find MAPDL log files more easily.

To set the logger output file to mylog.log, run the following commands in a Python terminal or at the beginning of your script:

import os
from ansys.mapdl.core import LOG

LOG.setLevel("DEBUG")
LOG.log_to_file("mylog.log")

from ansys.mapdl.core import launch_mapdl

# Using current directory as ``run_location``
mapdl = launch_mapdl(run_location=os.getcwd(), loglevel="DEBUG")

If you know the location of the executable file, you can set it as the first parameter of the launch_mapdl() function.

from ansys.mapdl.core import launch_mapdl

exec_loc = "C:/Program Files/ANSYS Inc/v241/ansys/bin/winx64/ANSYS241.exe"
mapdl = launch_mapdl(exec_loc, run_location=os.getcwd(), loglevel="DEBUG")

If you do not specify the location of the executable file, PyMAPDL uses the default location.

注釈

If MAPDL launches when you specify the location of the executable file but not when you don't specify it, the cached executable location is likely outdated. To update it, see

Update the cached executable location.

If MAPDL is not launching, check the content of log files in the current directory (specified using run_location) for more information on the issue. The main MAPDL log file is .__tmp__.out. This is the output file specified in the command line. If the launching is successful, it should show:

Start GRPC Server

##############################
### START GRPC SERVER      ###
##############################

Server Executable   : MapdlGrpc Server
Server listening on : 0.0.0.0:50052

Or, from Ansys MAPDL 2026R1, it should show:

################################################
#####    *INSECURE* GRPC SERVER STARTED    #####
################################################
Transport Mode           : INSECURE
Server Executable        : MapdlGrpc.Server
Server listening on      : 0.0.0.0:50052
Allow remote connections : True

 Press Ctrl-C to stop the server...

Additionally, MAPDL generates other files such as file1.out, file1.err, and file1.log that can be useful to identify the issue.

The main logger file LOG (in the example, recorded to my_log.log) also provides valuable information about startup. Here is an extract:

DEBUG - pymapdl_global -  launcher - launch_mapdl - Starting MAPDL
DEBUG - pymapdl_global -  launcher - generate_mapdl_launch_command - Generated command: C:\Program Files\ANSYS Inc\v242\ansys\bin\winx64\ansys242.exe -j file -np 2 -b -i .__tmp__.inp -o .__tmp__.out -port 50055 -grpc
INFO - pymapdl_global -  launcher - launch_grpc -
============
============
Running an MAPDL instance
Location:
C:\Users\user\AppData\Local\Temp\ansys_ymjqvmeyww
Command:
C:\Program Files\ANSYS Inc\v242\ansys\bin\winx64\ansys242.exe -j file -np 2 -b -i .__tmp__.inp -o .__tmp__.out -port 50055 -grpc
Env vars:
{'ANSYS242_DIR': 'C:\\Program Files\\ANSYS Inc\\v242\\ANSYS', 'AWP_ROOT242': 'C:\\Program Files\\ANSYS Inc\\v242\\ANSYS',  ... }
============
============
DEBUG - pymapdl_global -  launcher - launch_grpc - Writing temporary input file: .__tmp__.inp with 'FINISH' command.
DEBUG - pymapdl_global -  launcher - launch_grpc - MAPDL starting in background.

From the preceding information, you can also extract the launch location (C:\Users\user\AppData\Local\Temp\ansys_ymjqvmeyww), the command used (C:\Program Files\ANSYS Inc\v242\ansys\bin\winx64\ansys242.exe -j file -np 2 -b -i .__tmp__.inp -o .__tmp__.out -port 50055 -grpc), and the environment variables (such as ANSYS242_DIR and AWP_ROOT242). This information can also help you find the MAPDL logs or the cause of the issue.

If MAPDL still does not launch, see Launching issues for more information on common issues and their solutions.

If after examining all the log files you cannot identify the issue, open a discussion on the PyMAPDL Discussions page. If you believe you have found a bug, create an issue on the PyMAPDL Issues page. You can attach the log file to the bug report for further investigation.

Location of the executable file#

Manually set the location of the executable file#

If you have a non-standard install, PyMAPDL might be unable to find your MAPDL installation. If this is the case, provide the location of MAPDL as the first parameter to the launch_mapdl() function.

Windows

>>> from ansys.mapdl.core import launch_mapdl
>>> exec_loc = "C:/Program Files/ANSYS Inc/v241/ansys/bin/winx64/ANSYS241.exe"
>>> mapdl = launch_mapdl(exec_loc)

Linux

>>> from ansys.mapdl.core import launch_mapdl
>>> exec_loc = "/usr/ansys_inc/v241/ansys/bin/ansys241"
>>> mapdl = launch_mapdl(exec_loc)

Default location of the executable file#

The first time that you run PyMAPDL, it detects the available Ansys installations.

Ansys installations are normally under:

Windows

C:/Program Files/ANSYS Inc/vXXX

Linux

/usr/ansys_inc/vXXX

Or under:

/ansys_inc/vXXX

By default, the Ansys installer uses the former one (/usr/ansys_inc) but also creates a symbolic link to the latter one (/ansys_inc).

Update the cached executable location#

The first time PyMAPDL finds a valid Ansys installation, it caches its path in the configuration file, config.txt. The path for this file is shown in this code:

>>> from ansys.mapdl.core.launcher import CONFIG_FILE
>>> print(CONFIG_FILE)
'C:\\Users\\user\\AppData\\Local\\ansys_mapdl_core\\ansys_mapdl_core\\config.txt'

In certain cases, this configuration file might become obsolete. For example, when a new Ansys version is installed and an earlier installation is removed.

To update this configuration file with the latest path, use:

>>> from ansys.mapdl.core import save_ansys_path
>>> save_ansys_path(r"C:\Program Files\ANSYS Inc\v241\ansys\bin\winx64\ansys241.exe")
'C:\\Program Files\\ANSYS Inc\\v241\\ansys\\bin\\winx64\\ansys241.exe'

If you want to see which Ansys installations PyMAPDL has detected, use:

>>> from ansys.mapdl.core import get_available_ansys_installations
>>> get_available_ansys_installations()
{242: 'C:\\Program Files\\ANSYS Inc\\v242',
241: 'C:\\Program Files\\ANSYS Inc\\v241',
-242: 'C:\\Program Files\\ANSYS Inc\\ANSYS Student\\v242'}

Student versions are provided as negative versions because the Python dictionary does not accept two equal keys. The result of the get_available_ansys_installations() method lists higher versions first and student versions last.

警告

You should not have the same Ansys product version and student version installed. For more information, see Conflicts with student version.

PyMAPDL usage issues#

Issues when importing and exporting NumPy arrays in MAPDL#

Because of the way MAPDL is designed, there is no way to store an array where one or more dimensions are zero. This can happen in NumPy arrays, where the first dimension can be set to zero. For example:

>>> import numpy
>>> from ansys.mapdl.core import launch_mapdl
>>> mapdl = launch_mapdl()
>>> my_array = np.reshape([1, 2, 3, 4], (4,))
>>> my_array
array([1, 2, 3, 4])

These types of array dimensions are always converted to 1.

For example:

>>> mapdl.parameters["mapdlarray"] = my_array
>>> mapdl.parameters["mapdlarray"]
array([[1.],
   [2.],
   [3.],
   [4.]])
>>> mapdl.parameters["mapdlarray"].shape
(4, 1)

This means that when you pass two arrays—one with the second axis equal to zero (for example, my_array) and another with the second axis equal to one—they have the same shape when later retrieved.

>>> my_other_array = np.reshape([1, 2, 3, 4], (4, 1))
>>> my_other_array
array([[1],
   [2],
   [3],
   [4]])
>>> mapdl.parameters["mapdlarray_b"] = my_other_array
>>> mapdl.parameters["mapdlarray_b"]
array([[1.],
   [2.],
   [3.],
   [4.]])
>>> np.allclose(mapdl.parameters["mapdlarray"], mapdl.parameters["mapdlarray_b"])
True

PyMAPDL stability#

Recommendations#

When connecting to an instance of MAPDL using gRPC (default), there are some cases where the MAPDL server might exit unexpectedly. There are several ways to improve MAPDL performance and stability:

Use `mute` to improve stability#

When possible, pass mute=True to individual MAPDL commands or set it globally with the Mapdl.mute method. This disables streaming back the response from MAPDL for each command and marginally improves performance and stability. Consider having a debug flag in your program or script so that you can turn on and off logging and verbosity as needed.

Known Issues#

MAPDL 2021 R1 has a stability issue with the Mapdl.input() method. Avoid using input files if possible. Attempt to use the Mapdl.upload() method to upload nodes and elements and read them in via the Mapdl.nread() and Mapdl.eread() methods.

More help needed?#

"What do I do if an issue is not listed here?"

To see if your issue is already posted, search the PyMAPDL Issues page. If not, do one of the following:

If you are not sure of the cause or would like some explanation about the usage of the function or its documentation, create a discussion on the PyMAPDL Discussions page.
If you believe you have found a bug or want to create a feature request, create an issue on the PyMAPDL Issues page.

For more complex issues or queries, contact the PyAnsys Core team.

Troubleshooting PyMAPDL#

Debug PyMAPDL#

Launching issues#

Updating MAPDL installation#

Connection timeout#

Testing MAPDL launching#

Message Passing Interface (MPI) issues#

Licensing issues#

Incorrect licensing environment variables#

Virtual private network (VPN) issues#

Missing dependencies on Linux#

Conflicts with student version#

Incorrect environment variables#

Using a proxy server#

Firewall settings#

Location of the executable file#

Manually set the location of the executable file#

Default location of the executable file#

Update the cached executable location#

PyMAPDL usage issues#

Issues when importing and exporting NumPy arrays in MAPDL#

PyMAPDL stability#

Recommendations#

Use `mute` to improve stability#

Known Issues#

More help needed?#

Troubleshooting PyMAPDL#

Debug PyMAPDL#

Launching issues#

Updating MAPDL installation#

Connection timeout#

Testing MAPDL launching#

Message Passing Interface (MPI) issues#

Licensing issues#

Incorrect licensing environment variables#

Virtual private network (VPN) issues#

Missing dependencies on Linux#

Conflicts with student version#

Incorrect environment variables#

Using a proxy server#

Firewall settings#

Location of the executable file#

Manually set the location of the executable file#

Default location of the executable file#

Update the cached executable location#

PyMAPDL usage issues#

Issues when importing and exporting NumPy arrays in MAPDL#

PyMAPDL stability#

Recommendations#

Use mute to improve stability#

Known Issues#

More help needed?#

Use `mute` to improve stability#