Scripting for Mechanical Engineers

| 06.12.2024

Introduction

If you've stumbled upon this article, you've probably already heard a lot of buzz-words around scripting capabilities with Ansys: automation, customization, PyAnsys, ACT, DPF, Python Objects, etc. You're probably feeling a little bit lost with all of this, do not fully understand the different capabilities and don't know where and how to start. This article hopes to clarify and to make you feel more confident about getting started.

A little bit of history

Scripting has always being part of Ansys' DNA. Back in the days when only Ansys Classic existed, many users by-passed the GUI and created their Finite Element models by directly writing Ansys code: MAPDL, which stands for Mechanical Ansys Parametric Design Language. The input file sent to Mechanical APDL solver is written in MAPDL. When Ansys moved to Workbench and Mechanical, a more user-friendly GUI was proposed, but anything created in this interface is actually only writting MAPDL which is sent to the solver through the same input file as if the model was created in Ansys Classic.

Ansys Classic and Workbench Mechanical both rely on MAPDL

More recently, new needs emerged among our users: going faster, and customizing the software to their own needs. This is why Python Scripting functionalities were introduced. In the rest of this article, we'll focus on these Python Scripting capabilites.

Why would I want to script anything?

Using Python scripting can help you in many different ways:

  • saving time (and money!) by automating repetitive tasks or even entire simulation workflows,
  • improving the robustness of your model setups,
  • customizing the tools to your own needs,
  • allowing more people to reuse your know-how.

Scripting tools offered by Ansys

There are two main ways of doing scripting with Ansys: In-Product scripting, and PyAnsys scripting.

  • In-Product scripting is the first possibility that was introduced. Basically, you'll be opening one of the Ansys products such as Discovery or Mechanical, and creating/executing scripts from this interface.
  • PyAnsys is a more recent method, which offers a way to connect to one or several Ansys products or technologies from an external Python environment. That allows easy integration of simulation into your own workflows.

Schematic of working with In-Product Scripting or PyAnsys Scripting

In the two next sections, we'll be giving more information on each of these methods.

In-Product Scripting

Many Ansys products offer scripting capabilities:

  • Scripting at the Workbench project page level can be used to create component systems, materials data, etc.
  • Geometry editors such as SpaceClaim or Discovery allow creation of geometry through scripting.
  • Mechanical offers large scripting capabilities, amongst which automation of the model setup and postprocessing.

Examples of In-Product Scripting

Scripting inside Mechanical

Creating a script inside Mechanical usually starts in the Mechanical Scripting interface. There are recording capabilities to help you find the commands.

Mechanical Scripting interface

Once the script is ready, there are many options to save and execute that script in the model:

  • The script can be saved to a user-button that can be triggered on-demand.
  • The Python Code object enables to execute Python code in response to events occurring in Mechanical for a given workflow.
    • The events related to Python code execution can be split into two main categories:
      • Use Python API to query information about the data model and inject MAPDL commands into the solver input file at different points in the construction of the input file.
      • Execute Python code based on events in Mechanical.
    • The details' view of this object can be customized in the Property Provider editor, to define user inputs and outputs, and allow parametrization.
  • The Python Result object enables computing and plotting customized data onto the Mechanical model.
    • This object uses the Data Processing Framework (DPF) post-processing toolbox (explained later in this article).
    • The details' view of this object can also be customized in the Property Provider editor, to define user inputs and outputs, and allow parametrization.

Hiding source code, additional customization, guided workflows

The Ansys Customization Toolkit allows to encapsulate and distribute scripts and "know-how" in an intuitive way. It can be used to:

  • create customized boundary conditions and loads,
  • guide and automate simulation worflows using wizards,
  • hide the source code from end users.

Ansys Customization Toolkit (ACT) can be used for further customization

PyAnsys

The PyAnsys project is a collection of Python librairies that allows to interface with Ansys products in a pythonic manner. This is an open-source project. PyAnsys offers a way to integrate simulation into your own Python workflows.

PyAnsys is a bridge that allows you to connect simulation to your workflows

There are many librairies available, and the best way to learn about them all is to have a look at the PyAnsys documentation. These packages can be separated into three categories:

  • Simulation librairies: PyMAPDL, PyMechanical, PyAEDT, PyFluent, ....
  • Utility librairies: PyPrimeMesh, PyDynamicReporting, PyAnsysGeometry, ...
  • Post-processing librairies: PyDPF, PyEnsight,... Below is an illustration of the most useful packages for structural engineers:

Most important PyAnsys librairies for structural simulations

PyAnsys code can be written and executed in any Integrated Development Environment (IDE) that is able to execute Python code.

Running a series of structural analyses from a Python environment thanks to PyMAPDL

It is also possible to use Python to create WebApps. Several Python packages allow for easy development of the front-end (the user interface), while the back-end (ie, the simulation) can be performed using one or several PyAnsys packages.

Sloshing analysis from a WebApp thanks to PyAnsys

What's DPF?

The Data Processing Framework (DPF) is a toolbox for accessing and transforming simulation data. It can access data from solver result files as well as several neutral formats (csv, hdf5, vtk, etc.). Various operators are available enabling the manipulation and the transformation of this data. DPF is a workflow-based framework that enables simple as well as complex evaluations by chaining operators. The data in DPF is defined based on physics agnostic mathematical quantities described in a self-sufficient entity called field. This allows DPF to be a modular and easy to use tool with a large range of capabilities. It is a product designed to handle large amounts of data.

DPF can be used both in Mechanical or in PyAnsys.

DPF is available both in Mechanical and in PyAnsys

  • DPF in Mechanical is usually used inside a Python Result to extract data, compute customized data, and plot it back to the model.

Example of Python Result: expanding generalized axisymmetric results

  • Within the PyAnsys project, DPF will typically be used to extract data from a binary Ansys result file, and compute new data and plot it.

Example of using PyDPF: extracting force reactions on bolts from the binary result file

Where do I start ? Where do I get help?

This section will provide you with information and links to help you get started.

Which scripting approach should I choose?

The one that suits you! If you're happy working within the Ansys products, stay there! If you want to integrate simulation into an external workflow built in Python, PyAnsys is for you. The below graphs can offer some guidelines as to which tool can be used, but is not a strict rule.

Choosing between various technologies in Mechanical

Choosing between various technologies for developing guided workflows

Ansys Developer Portal and Forum

The Ansys Developer Portal is the best starting place for scripting. It will help you find all the other platforms listed below. The Ansys Developer Forum is the best place to ask questions, and to check already answered posts and examples (there are tons!).

Getting support

We encourage you to ask your scripting questions in the Ansys Developer Forum, so that the entire scripting community can participate to and benefit from this discussion. Bugs or enhancement requests related to PyAnsys should be reported by opening an issue on Github, in the appropriate repository. For scripting questions or issues related to In-Product Scripting, you can also contact your local support provider. Please note that support on PyAnsys is not provided through the standard support platforms, and refer to the PyAnsys Clarifications for further information.

Documentation

The In-Product Scripting documentation can be found in the Product documentation. Here are some specific links:

The PyAnsys documentation can be accessed from Github or directly at PyAnsys Docs.

Training material

Many useful courses are available on the Ansys Innovation Space and the Ansys Learning Hub:

  • Ansys Mechanical Scripting
  • Introduction to Python
  • Scripting with Ansys Discovery
  • Introduction to Ansys Data Processing Framework (DPF)
  • Introduction to ACT in Mechanical
  • Introduction to ACT Wizards
  • Getting started with PyMAPDL
  • Developing WebApps for modeling and simulation using PyAnsys
  • ...

Conclusion

We hope that this article has helped you better understand the different scripting capabilities offered with and around Ansys and we look forward to hearing from you in the Ansys Developer Forum for your first question ;-).

Connect with Ansys