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.