User guide#
This section provides a general overview of PyMAPDL and how you use it.
PyMAPDL overview#
The launch_mapdl()
function
within the ansys-mapdl-core
library creates an instance of the
Mapdl
class in the background and sends
commands to that instance. Errors and warnings are processed
Pythonically, letting you develop a script in real time, without
worrying about it functioning correctly when deployed in batch
mode.
MAPDL can be started from Python in gRPC mode using the
launch_mapdl()
method. This starts
MAPDL in a temporary directory by default. You can change this to
your current directory with this code:
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 Python class. For example, if you wanted to create a surface using key points, you 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, which 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.
This MapdlRuntimeError
was caught immediately. This means that
you can write your MAPDL scripts in Python, run them interactively, and
then run them as a batch without worrying if the script would run correctly if
you had instead outputted it to a script file.
The Mapdl
class supports much more
than just sending text to MAPDL. It includes higher-level wrapping,
allowing for better scripting and interaction with MAPDL. For an overview of the
various advanced methods to visualize, script, and interact with MAPDL, see
Examples.
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, it’s easier
to script because ansys-mapdl-core
takes care of the string formatting for you.
For example, you can input points from a numpy array with:
# 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, you 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 Mapdl
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 with 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 is then redefined. A keypoint 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.
For stability considerations, see PyMAPDL stability.