Skip to main content

Exploring PyMechanical access methods: A brief overview

| 07.25.2023

Scripting plays a crucial role in interacting with software products, enabling automation of routine tasks. Ansys Mechanical offers a powerful scripting capability called "Mechanical Scripting" to address automation requirements. As part of Ansys’ commitment to expanding our ability to support our users' needs for complex workflows and more control over their processes, we have added PyMechanical to our PyAnsys suite of tools.

In this article, we will explore the relation between Mechanical Scripting and PyMechanical. Whether you are looking to streamline simulations, control input decks, perform proof-of-concept studies, or integrate Ansys Mechanical with other Python modules, PyMechanical provides the flexibility and efficiency you need.

With PyMechanical, you can accomplish tasks like these:

  • Accelerate the preparation of your simulations.
  • Combine the expressiveness of general-purpose Python code to control the flow in your input decks with methods that drive the solver.
  • Explore proof-of-concept studies or capture knowledge using interactive Jupyter notebooks.
  • Tap the solver as the physics engine in your next AI app.


Automation via Mechanical Scripting

Inside Ansys Mechanical, automation requirements can be addressed with Mechanical Scripting. For example, a script that counts the number of bodies in the geometry can be written as:

allbodies = ExtAPI.DataModel.Project.Model.GetChildren(DataModelObjectCategory.Body, True)

For more information on Mechanical Scripting capabilities, please refer to the Scripting in Mechanical Guide.


Automation via PyMechanical

If you are already using Python to automate and coordinate your workflows, you can now leverage PyMechanical as an interface to the Mechanical Scripting Interface. It is important to note that PyMechanical uses Standalone Mechanical, a beta feature that enables you to open a standalone version of Ansys Mechanical. This standalone version operates independently of Ansys whilst offering similar features. The differences are slight, and if you are well versed in the use of Mechanical, you should be able to use the standalone version with ease. Launching Standalone Mechanical is done with the following command:

"C:/Program Files/ANSYS Inc/v232/aisol/bin/winx64/AnsysWBU.exe" -DSApplet -AppModeMech

Standalone Mechanical documentation (requires login).


PyMechanical Interfaces

PyMechanical offers two distinct modes for interacting with the Mechanical solver:

  • Remote session: uses PyMechanical as a client to a remote Mechanical instance.
  • Embedded instance: uses PyMechanical to embed an instance of Mechanical directly within Python as a Python object.

We will provide a brief overview at how to instantiate both of these modes. If you are unfamiliar with, or do not have a virtual Python environment to use, please refer to the Ansys Python Manager article which can help you get started. Ansys Python Manager simplifies the process of deploying a virtual environment along with all the required Ansys modules for PyMechanical.

Instead of the command in the previous section to launch standalone Mechanical, one can use the following command (more details can be found in the documentation) in an environment that has the PyMechanical library installed:

ansys-mechanical -g 


Remote Mechanical Sessions

In this mode, Mechanical runs as a server, ready to respond to any clients and PyMechanical acts as a client making API calls behind the scenes. To start a remote session of Mechanical on your local computer from Python, simply use the launch_mechanical() method. This creates an instance of the Mechanical class in the background and sends commands to it. The method returns an object representing the connection to the session. This works with interactive mode in Python and allows you to develop scripts in real time, before you run your work as a program (or in batch mode).

import ansys.mechanical.core as pymechanical
mechanical = pymechanical.launch_mechanical(batch=False)

When Mechanical is active, you can send commands to it via the connection object, including Python scripts as strings which are evaluated at the other end. For example, you can send any Python script by storing it as a string.

result = mechanical.run_python_script("2+3")
result = mechanical.run_python_script("ExtAPI.DataModel.Project.ProjectDirectory")

With batch=False argument on launch_mechanical() method, one can observe the effect of the script:

To manually connect to a local/remote session launched using standalone mechanical, use the Mechanical() method. You can find details about this method in Connecting to a remote session.

Below is the complete code, and results from the body count as above:

import ansys.mechanical.core as pymechanical
mechanical = pymechanical.launch_mechanical()

file =  r'D:\\Workdir\\bracket.mechdb'  # mechdb is a Standalone Mechanical filetype
command = f'ExtAPI.DataModel.Project.Open("{file}")'
mechanical.run_python_script("allbodies=ExtAPI.DataModel.Project.Model.GetChildren( DataModelObjectCategory.Body,True)")


Embedded Instances

In this mode, PyMechanical directly embeds a Mechanical instance as a Python object, and a Mechanical object is directly loaded into Python memory. No external instance of Mechanical is running. This embedded instance feature is supported on Windows starting from version 2023 R1, and it is supported on Linux from version 2023 R2.

Below is the code to get the body count as before.

from ansys.mechanical.core import App, global_variables
app = App(version=232)

file =  r'D:\\Workdir\\bracket.mechdb'
allbodies=ExtAPI.DataModel.Project.Model.GetChildren( Ansys.Mechanical.DataModel.Enums.DataModelObjectCategory.Body,True)

The command line mode was used just for demonstration. Please note that, in either of the modes, you can execute a Python script file that has these commands.

(pymech_test) PS D:\Workdir\pymechanical> python .\


Try PyMechanical

This is just an overview to introduce you to PyMechanical. For further exploration, please refer to the complete documentation.

In conclusion, PyMechanical empowers Method Developers, Engineers and Researchers to unlock the full potential of Ansys Mechanical by bringing it into the world of Python. Whether you choose to use PyMechanical as a client to a remote Mechanical session or embed an instance of Mechanical as a Python object, you can expand automation and integration possibilities with a wide array of Python functionalities.