PyMAPDL language and usage#

This page gives you an overview of the PyMAPDL API for the Mapdl class. For more information, see Mapdl module.

APDL command logging#

While ansys-mapdl-core is designed to make it easier to control an APDL session by calling it using Python, it might be necessary to call MAPDL again using an input file generated from a PyMAPDL script. This is automatically enabled with the log_apdl='apdl.log' parameter. Enabling this parameter causes the Mapdl class to write each command run into a log file named "apdl.log" in the active Mapdl.directory. For example:

>>> from ansys.mapdl.core import launch_mapdl

>>> ansys = launch_mapdl(log_apdl="apdl.log")
>>> ansys.prep7()
>>> ansys.k(1, 0, 0, 0)
>>> ansys.k(2, 1, 0, 0)
>>> ansys.k(3, 1, 1, 0)
>>> ansys.k(4, 0, 1, 0)

This code writes the following to the "apdl.log" file:

/PREP7,
K,1,0,0,0
K,2,1,0,0
K,3,1,1,0
K,4,0,1,0

This allows for the translation of a Python script to an APDL script except for conditional statements, loops, or functions.

Use the `lgwrite` method#

Alternatively, if you only want the database command output, you can use the Mapdl.lgwrite method to write the entire database command log to a file.

Interactive breakpoint#

In most circumstances, it is necessary or preferable to open up the MAPDL GUI. The Mapdl class has the Mapdl.open_gui() method, which allows you to seamlessly open up the GUI without losing work or having to restart your session. For example:

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

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)

Open up the GUI

>>> mapdl.open_gui()

Resume where you left off

>>> mapdl.et(1, "MESH200", 6)
>>> mapdl.amesh("all")
>>> mapdl.eplot()

This approach avoids the hassle of having to switch back and forth between an interactive session and a scripting session. Instead, you can have one scripting session and open up a GUI from the scripting session without losing work or progress. Additionally, none of the changes made in the GUI affect the script. You can experiment in the GUI, and the script is left unaffected.

Run a batch job#

Instead of running a MAPDL batch by calling MAPDL with an input file, you can instead define a function that runs MAPDL. This example runs a mesh convergence study based on the maximum stress of a cylinder with torsional loading.

import numpy as np
from ansys.mapdl.core import launch_mapdl


def cylinder_batch(elemsize, plot=False):
    """Report the maximum von Mises stress of a Cantilever supported cylinder"""

    # clear
    mapdl.finish()
    mapdl.clear()

    # cylinder parameters
    radius = 2
    h_tip = 2
    height = 20
    force = 100 / radius
    pressure = force / (h_tip * 2 * np.pi * radius)

    mapdl.prep7()
    mapdl.et(1, 186)
    mapdl.et(2, 154)
    mapdl.r(1)
    mapdl.r(2)

    # Aluminum properties (or something)
    mapdl.mp("ex", 1, 10e6)
    mapdl.mp("nuxy", 1, 0.3)
    mapdl.mp("dens", 1, 0.1 / 386.1)
    mapdl.mp("dens", 2, 0)

    # Simple cylinder
    for i in range(4):
        mapdl.cylind(radius, "", "", height, 90 * (i - 1), 90 * i)

    mapdl.nummrg("kp")

    # mesh cylinder
    mapdl.lsel("s", "loc", "x", 0)
    mapdl.lsel("r", "loc", "y", 0)
    mapdl.lsel("r", "loc", "z", 0, height - h_tip)
    # mapdl.lesize('all', elemsize*2)
    mapdl.mshape(0)
    mapdl.mshkey(1)
    mapdl.esize(elemsize)
    mapdl.allsel("all")
    mapdl.vsweep("ALL")
    mapdl.csys(1)
    mapdl.asel("s", "loc", "z", "", height - h_tip + 0.0001)
    mapdl.asel("r", "loc", "x", radius)
    mapdl.local(11, 1)
    mapdl.csys(0)
    mapdl.aatt(2, 2, 2, 11)
    mapdl.amesh("all")
    mapdl.finish()

    if plot:
        mapdl.view(1, 1, 1, 1)
        mapdl.eplot()

    # new solution
    mapdl.slashsolu()
    mapdl.antype("static", "new")
    mapdl.eqslv("pcg", 1e-8)

    # Apply tangential pressure
    mapdl.esel("s", "type", "", 2)
    mapdl.sfe("all", 2, "pres", "", pressure)

    # Constrain bottom of cylinder/rod
    mapdl.asel("s", "loc", "z", 0)
    mapdl.nsla("s", 1)

    mapdl.d("all", "all")
    mapdl.allsel()
    mapdl.psf("pres", "", 2)
    mapdl.pbc("u", 1)
    mapdl.solve()
    mapdl.finish()

    # access results using MAPDL object
    result = mapdl.result

    # to access the results you could have run:
    # from ansys.mapdl import reader as pymapdl_reader
    # resultfile = os.path.join(mapdl.path, '%s.rst' % mapdl.jobname)
    # result = pymapdl_reader.read_binary(result file)

    # Get maximum von Mises stress at result 1
    # Index 0 as it's zero based indexing
    nodenum, stress = result.principal_nodal_stress(0)

    # von Mises stress is the last column
    # must be nanmax as the shell element stress is not recorded
    maxstress = np.nanmax(stress[:, -1])

    # return number of nodes and max stress
    return nodenum.size, maxstress


# initialize MAPDL
mapdl = launch_mapdl(override=True, loglevel="ERROR")

# call MAPDL to solve repeatedly
result_summ = []
for elemsize in np.linspace(0.6, 0.15, 15):
    # run the batch and report the results
    nnode, maxstress = cylinder_batch(elemsize, plot=False)
    result_summ.append([nnode, maxstress])
    print(
        "Element size %f: %6d nodes and maximum vom Mises stress %f"
        % (elemsize, nnode, maxstress)
    )

# Exit MAPDL
mapdl.exit()

Here is the output from the script:

Element size 0.600000:   9657 nodes and maximum vom Mises stress 142.623505
Element size 0.567857:  10213 nodes and maximum vom Mises stress 142.697800
Element size 0.535714:  10769 nodes and maximum vom Mises stress 142.766510
Element size 0.503571:  14177 nodes and maximum vom Mises stress 142.585388
Element size 0.471429:  18371 nodes and maximum vom Mises stress 142.825684
Element size 0.439286:  19724 nodes and maximum vom Mises stress 142.841202
Element size 0.407143:  21412 nodes and maximum vom Mises stress 142.945984
Element size 0.375000:  33502 nodes and maximum vom Mises stress 142.913437
Element size 0.342857:  37877 nodes and maximum vom Mises stress 143.033401
Element size 0.310714:  59432 nodes and maximum vom Mises stress 143.328842
Element size 0.278571:  69106 nodes and maximum vom Mises stress 143.176086
Element size 0.246429: 110547 nodes and maximum vom Mises stress 143.499329
Element size 0.214286: 142496 nodes and maximum vom Mises stress 143.559128
Element size 0.182143: 211966 nodes and maximum vom Mises stress 143.953430
Element size 0.150000: 412324 nodes and maximum vom Mises stress 144.275406

Chain commands in MAPDL#

MAPDL permits several commands on one line by using the separation character "$". This can be utilized within PyMAPDL to effectively chain several commands together and send them to MAPDL for execution rather than executing them individually. Chaining commands can be helpful when you need to execute thousands of commands in a Python loop and don’t need the individual results for each command. For example, if you want to create 1000 key points along the X axis, you would run:

xloc = np.linspace(0, 1, 1000)
for x in xloc:
    mapdl.k(x=x)

However, because each command executes individually and returns a response, it is much faster to send the commands to be executed by MAPDL in groups and have the Mapdl class handle grouping the commands by using the Mapdl.chain_commands attribute.

xloc = np.linspace(0, 1, 1000)
with mapdl.chain_commands:
    for x in xloc:
        mapdl.k(x=x)

The execution time using this approach is generally 4 to 10 times faster than running each command individually. You can then view the final response of the chained commands with the Mapdl.last_response attribute.

Note

Command chaining is not supported in distributed MAPDL. To improve performances, use the mute=True or Mapdl.non_interactive context manager.

Sending arrays to MAPDL#

You can send numpy arrays or Python lists directly to MAPDL using the Mapdl.Parameters attribute. This is far more efficient than individually sending parameters to MAPDL through Python with the Mapdl.run() method because it uses the Mapdl.vread() method behind the scenes.

from ansys.mapdl.core import launch_mapdl
import numpy as np

mapdl = launch_mapdl()
arr = np.random.random((5, 3))
mapdl.parameters["MYARR"] = arr

Verify that the data has been properly loaded to MAPDL by indexing the Mapdl.Parameters attribute as if it was a Python dictionary:

>>> array_from_mapdl = mapdl.parameters["MYARR"]
>>> array_from_mapdl
array([[0.65516567, 0.96977939, 0.3224993 ],
       [0.58634927, 0.84392263, 0.18152529],
       [0.76719759, 0.45748876, 0.56432361],
       [0.78548338, 0.01042177, 0.57420062],
       [0.33189362, 0.9681039 , 0.47525875]])

Download a remote MAPDL file#

When running MAPDL in gRPC mode, remote MAPDL files can be listed and downloaded using the Mapdl class with the Mapdl.download() function. For example, the following code lists the remote files and downloads one of them:

remote_files = mapdl.list_files()

# ensure the result file is one of the remote files
assert "file.rst" in remote_files

# download the remote result file
mapdl.download("file.rst")

Note

This feature is only available in MAPDL 2021 R1 and later.

Alternatively, you can download several files at once using the glob pattern or a list of file names in the Mapdl.download() method:

# Using a list of file names
mapdl.download(["file0.log", "file1.out"])

# Using glob pattern to match the list_files
mapdl.download("file*")

You can also download all files in the MAPDL working directory (Mapdl.directory) using this function:

mapdl.download_project()

Or, filter by extensions as shown in this example:

mapdl.download_project(
    ["log", "out"], target_dir="myfiles"
)  # Download the files to 'myfiles' directory

Upload a local MAPDL file#

You can upload a local MAPDL file as the remote MAPDL instance with the Mapdl.upload() method:

# upload a local file
mapdl.upload("sample.db")

# ensure the uploaded file is one of the remote files
remote_files = mapdl.list_files()
assert "sample.db" in remote_files

Note

This feature is only available in MAPDL 2021 R1 and later.

Unsupported MAPDL commands and other considerations#

Most MAPDL commands have been mapped Pythonically into their equivalent methods. Some commands, however, are not supported because either they are not applicable to an interactive session or they require additional commands that are incompatible with the way inputs are handled on the MAPDL server.

Unavailable commands#

Some commands are unavailable in PyMAPDL for a variety of reasons.

Some of these commands do not make sense in a Python context. Here are some examples:

The *ASK command can be replaced with a Python input.
The *IF command can be replaced with a Python if statement.
The *CREATE and *USE commands can be replaced with calls to another Python function or module.

Other commands do not make sense in a non-GUI session. For example, the /ERASE and ERASE commands that clear the graphics screen are not needed in a non-GUI session.

Other commands are quietly ignored by MAPDL, but you can still use them. For example, the /BATCH command can be run using the mapdl.run("/BATCH") method, which returns the following warning:

*** WARNING ***                         CP =       0.519   TIME= 12:04:16
The /BATCH command must be the first line of input.  The /BATCH command
is ignored.

Table-1 Comprehensive information on commands that are unavailable

Table 1. Non-available commands.

	MAPDL command	Interactive	Non-interactive	Direct run	Notes
GUI commands	`*ASK`	❌ Not available	❌ Not available	✅ Works	When used in `mapdl.run()` it automatically assumes the user input is 0. Use Python `input` instead.
	`*VEDIT`	❌ Not available	❌ Not available	❗ MAPDL shows a warning	It requires a GUI session to work.
	`/ERASE`	❌ Not available	❌ Not available	✅ Works	It does not make sense in a non-GUI session.
	`ERASE`	❌ Not available	❌ Not available	❗ MAPDL shows a warning	It does not make sense in a non-GUI session.
	`HELP`	❌ Not available	❌ Not available	❗ Ignored by MAPDL	It requires a GUI session to work.
	`HELPDISP`	❌ Not available	❌ Not available	❗ Ignored by MAPDL	It requires a GUI session to work.
	`NOERASE`	❌ Not available	❌ Not available	✅ Works	It does not make sense in a non-GUI session.
Control flow commands	`*CYCLE`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `continue`.
	`*DO`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `for`.
	`*DOWHILE`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `while`.
	`*ELSE`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `else`.
	`*ELSEIF`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `elif`.
	`*ENDDO`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords.
	`*GO`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, such as `if` or functions.
	`*IF`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords, in this case `continue`.
	`*REPEAT`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords such as `for` or `while`
	`*RETURN`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python control flow keywords such as `break`, `continue` or `return`
Others commands	`*DEL`	❌ Not available	❌ Not available	✅ Works	It is recommended to use Python variables (use Python memory) instead of MAPDL variables.
	`/BATCH`	❌ Not available	❌ Not available	❗ Ignored by MAPDL.	It does not make sense in a PyMAPDL session.
	`/EOF`	❌ Not available	❌ Not available	❌ PyMAPDL shows an exception	To stop the server, use `mapdl.exit()`
	`UNDO`	❌ Not available	❌ Not available	❗ MAPDL shows a warning	It does not undo any command.

Note

Interactive means there is a method in MAPDL, such as the Mapdl.prep7() method.
Non-interactive means it is run inside a Mapdl.non_interactive context block, the Mapdl.input() method, or the Mapdl.input_strings() method. For example:
```
with mapdl.non_interactive:
    mapdl.prep7()
```
Direct run means that the mapdl.run() method is used to run the MAPDL command. An example is the mapdl.run("/PREP7") method.

Note that running these commands with the mapdl.run() method does not cause MAPDL to exit. However, it might raise exceptions.

These MAPDL commands can also be executed using the mapdl.input() method or the mapdl.input_strings() method. The results should be same as running them in a normal batch MAPDL session.

Unsupported “interactive” commands#

The following commands can be only run in non-interactive mode (inside a Mapdl.non_interactive block or using the mapdl.input() method).

Table-2 provides comprehensive information on the “interactive” commands that are unsupported.

Table 2. Non-interactive only commands.

	Interactive	Non-interactive	Direct Run	Notes
`*CREATE`	❌ Not available	✅ Available	❗ Only in `Mapdl.non_interactive`	It is recommended to create Python functions instead.
`CFOPEN`	❌ Not available	✅ Available	❗ Only in `Mapdl.non_interactive`	It is recommended to use Python functions such as `open`.
`CFCLOSE`	❌ Not available	✅ Available	❗ Only in `Mapdl.non_interactive`	It is recommended to use Python functions such as `open`.
`*VWRITE`	❌ Not available	✅ Available	❗ Only in `Mapdl.non_interactive`	If you are working in a local session, it is recommended you use Python function such as `open`.
`*MWRITE`	❌ Not available	✅ Available	❗ Only in `Mapdl.non_interactive`	If you are working in a local session, it is recommended you use Python function such as `open`.
`LSWRITE`	✅ Available (Internally running in `Mapdl.non_interactive`)	✅ Available	❗ Only in `Mapdl.non_interactive`

Environment variables#

There are several PyMAPDL-specific environment variables that can be used to control the default behavior of PyMAPDL or launching MAPDL.

These environment variables do not have priority over the arguments given in the corresponding functions. Consider this command:

user@machine:~$ export PYMAPDL_PORT=50052
user@machine:~$ python -c "from ansys.mapdl.core import launch_mapdl; mapdl=launch_mapdl(port=60053)"

This command launches an MAPDL instance on port 60053 because the port argument has priority over the PYMAPDL_PORT environment variable. The following table describes all arguments.

`PYMAPDL_START_INSTANCE`	Override the behavior of the `ansys.mapdl.core.launcher.launch_mapdl()` function to only attempt to connect to existing instances of PyMAPDL. Generally used in combination with `PYMAPDL_PORT`. Example: user@machine:~$ export PYMAPDL_START_INSTANCE=True
`PYMAPDL_PORT`	Default port for PyMAPDL to connect to. Example: user@machine:~$ export PYMAPDL_PORT=50052
`PYMAPDL_IP`	Default IP for PyMAPDL to connect to. Example: user@machine:~$ export PYMAPDL_IP=123.45.67.89
`PYMAPDL_NPROC`	Default number of cores for MAPDL to use. Example: user@machine:~$ export PYMAPDL_NPROC=10
`ANSYSLMD_LICENSE_FILE`	License file or IP address with port in the format `PORT@IP`. Do not confuse with the `IP` and `PORT` where the MAPDL instance is running, which are specified using `PYMAPDL_IP` and `PYMAPDL_PORT`. This is helpful for supplying licensing for Docker. Example: user@machine:~$ export ANSYSLMD_LICENSE_FILE=1055@123.45.89
`PYMAPDL_MAPDL_EXEC`	Executable path from where to launch MAPDL instances. Example: user@machine:~$ export PYMAPDL_MAPDL_EXEC=/ansys_inc/v241/ansys/bin/mapdl
`PYMAPDL_MAPDL_VERSION`	Default MAPDL version to launch in case there are several versions availables. Example: user@machine:~$ export PYMAPDL_MAPDL_VERSION=22.2
`PYMAPDL_RUNNING_ON_HPC`	With this environment variable set to `FALSE`, you can avoid PyMAPDL from detecting that it is running on a SLURM HPC cluster.
`PYMAPDL_MAX_MESSAGE_LENGTH`	Maximum gRPC message length. If your connection terminates when running PRNSOL or NLIST, raise this. In bytes, defaults to 256 MB. Only for developing purposes.

PyMAPDL language and usage#

Overview#

Selecting entities#

Running in non-interactive mode#

How the non-interactive context manager works#

MAPDL macros#

Additional options when running commands#

Running several commands or an input file#

Conditional statements and loops#

Warnings and errors#

Prompts#

APDL command logging#

Use the `lgwrite` method#

Interactive breakpoint#

Run a batch job#

Chain commands in MAPDL#

Sending arrays to MAPDL#

Download a remote MAPDL file#

Upload a local MAPDL file#

Unsupported MAPDL commands and other considerations#

Unavailable commands#

Unsupported “interactive” commands#

Environment variables#

PyMAPDL language and usage#

Overview#

Selecting entities#

Running in non-interactive mode#

How the non-interactive context manager works#

MAPDL macros#

Additional options when running commands#

Running several commands or an input file#

Conditional statements and loops#

Warnings and errors#

Prompts#

APDL command logging#

Use the lgwrite method#

Interactive breakpoint#

Run a batch job#

Chain commands in MAPDL#

Sending arrays to MAPDL#

Download a remote MAPDL file#

Upload a local MAPDL file#

Unsupported MAPDL commands and other considerations#

Unavailable commands#

Unsupported “interactive” commands#

Environment variables#

Use the `lgwrite` method#