This guide provides a general overview of the basics and usage of the PyMAPDL library.
PyMAPDL Basic Overview¶
ansys-mapdl-core library creates an instance of of
Mapdl in the background and sends
commands to that service. Errors and warnings are processed
Pythonically letting the user develop a script real-time without
worrying about if it will function correctly when deployed in batch
MAPDL can be started from python in gRPC mode using
launch_mapdl(). This starts
MAPDL in a temporary directory by default. You can change this to
your current directory with:
import os from ansys.mapdl.core import launch_mapdl path = os.getcwd() mapdl = launch_mapdl(run_location=path)
MAPDL is now active and you can send commands to it as a genuine a Python class. For example, if we wanted to create a surface using keypoints we could run:
mapdl.run('/PREP7') mapdl.run('K, 1, 0, 0, 0') mapdl.run('K, 2, 1, 0, 0') mapdl.run('K, 3, 1, 1, 0') mapdl.run('K, 4, 0, 1, 0') mapdl.run('L, 1, 2') mapdl.run('L, 2, 3') mapdl.run('L, 3, 4') mapdl.run('L, 4, 1') mapdl.run('AL, 1, 2, 3, 4')
MAPDL interactively returns the result of each command and it is stored to the logging module. Errors are caught immediately. For example, if you input an invalid command:
>>> mapdl.run('AL, 1, 2, 3') MapdlRuntimeError: AL, 1, 2, 3 DEFINE AREA BY LIST OF LINES LINE LIST = 1 2 3 (TRAVERSED IN SAME DIRECTION AS LINE 1) *** ERROR *** CP = 0.338 TIME= 09:45:36 Keypoint 1 is referenced by only one line. Improperly connected line set for AL command.
MapdlRuntimeError was caught immediately, and this means that
you can write your MAPDL scripts in python, run them interactively and
then as a batch without worrying if the script will run correctly if
you had instead outputted it to a script file.
Mapdl class supports much more
than just sending text to MAPDL and includes higher level wrapping
allowing for better scripting and interaction with MAPDL. See the
Examples for an overview of the various advanced
methods to visualize, script, and interact with MAPDL.
Interactive Command output¶
The command output has stored the command and arguments that created it. You can inspect this command using:
>>> output = mapdl.prep7() >>> print(output.command()) prep7
or if you want to see only the command you can:
Calling MAPDL Pythonically¶
MAPDL functions can be called directly from an instance of
Mapdl in a pythonic manner. This is
to simplify calling ANSYS, especially when inputs are variables within
Python. For example, the following two commands are equivalent:
mapdl.k(1, 0, 0, 0) mapdl.run('K, 1, 0, 0, 0')
This approach has some obvious advantages, chiefly that it’s a easier
to script as
ansys-mapdl-core takes care of the string formatting for you.
For example, inputting points from a numpy array:
# make 10 random keypoints in ANSYS points = np.random.random((10, 3)) for i, (x, y, z) in enumerate(points): mapdl.k(i + 1, x, y, z)
Additionally, exceptions are caught and handled within Python.
>>> mapdl.run('AL, 1, 2, 3') Exception: AL, 1, 2, 3 DEFINE AREA BY LIST OF LINES LINE LIST = 1 2 3 (TRAVERSED IN SAME DIRECTION AS LINE 1) *** ERROR *** CP = 0.338 TIME= 09:45:36 Keypoint 1 is referenced by only one line. Improperly connected line set for AL command.
For longer scripts, instead of sending commands to MAPDL as in the area creation example, we can instead run:
# clear existing geometry mapdl.finish() mapdl.clear() # create a square area using keypoints mapdl.prep7() mapdl.k(1, 0, 0, 0) mapdl.k(2, 1, 0, 0) mapdl.k(3, 1, 1, 0) mapdl.k(4, 0, 1, 0) mapdl.l(1, 2) mapdl.l(2, 3) mapdl.l(3, 4) mapdl.l(4, 1) mapdl.al(1, 2, 3, 4)
This approach has some obvious advantages, chiefly that it’s a bit
easier to script as
takes care of the string formatting for you. For example, inputting
points from a numpy array:
import numpy as np # make 10 random keypoints in MAPDL points = np.random.random((10, 3)) for i, (x, y, z) in enumerate(points): mapdl.k(i + 1, x, y, z)
Additionally, each function with the MAPDL class has help associated within it. For example:
>>> help(mapdl.k) Help on method K in module ansys.mapdl.core.mapdl_grpc.MapdlGrpc: k(npt='', x='', y='', z='') method of ansys.mapdl.core.mapdl_grpc.MapdlGrpc instance Defines a keypoint. APDL Command: K Parameters ---------- npt Reference number for keypoint. If zero, the lowest available number is assigned [NUMSTR]. x, y, z Keypoint location in the active coordinate system (may be R, θ, Z or R, θ, Φ). If X = P, graphical picking is enabled and all other fields (including NPT) are ignored (valid only in the GUI). Examples -------- Create a keypoint at (1, 1, 2) >>> mapdl.k(1, 1, 1, 2) Notes ----- Defines a keypoint in the active coordinate system [CSYS] for line, area, and volume descriptions. A previously defined keypoint of the same number will be redefined. Keypoints may be redefined only if it is not yet attached to a line or is not yet meshed. Solid modeling in a toroidal system is not recommended.
Remote Stability Considerations¶
This is only valid for instances of MAPDL launched in 2021R1 or
newer launching with
When connecting to a remote instance of MAPDL, there are some cases where the MAPDL server will exit unexpectedly. These issues are being corrected and will be solved in 2021R2, but for the time being, there are several ways to improve performance and stability of MADPL:
When possible, pass
mute=Trueto individual MAPDL commands or set it globally with
Mapdl.mute. This disables streaming back the response from MAPDL for each command and will marginally improve performance and stability. Consider having a debug flag in your program or script so you can enable or disable logging and verbosity when needed.