Launching PyMechanical#

The ansys-mechanical-core package requires either a local or remote instance of Mechanical to communicate with. This page describes how Mechanical is installed from the Ansys standard installer and describes how you launch and interface with Mechanical from Python.

Install Mechanical#

Mechanical is installed by default from the Ansys standard installer. When you run the standard installer, look under the Structural Mechanics heading to verify that the Mechanical Products checkbox is selected. Although options in the standard installer might change, this image provides a reference:

../_images/unified_install_2023R1.jpg

Launch a remote Mechanical session#

You can use PyMechanical to launch a Mechanical session on the local machine Python is running on. Alternatively, you can run Mechanical’s command line directly on any machine to start Mechanical in server mode and then use its IP address to manually connect to it from Python.

Launch Mechanical on the local machine using Python#

When Mechanical is installed locally on your machine, you can use the launch_mechanical() method to launch and automatically connect to Mechanical. While this method provides the easiest and fastest way to launch Mechanical, it only works with a local Mechanical installation.

Launch Mechanical locally with this code:

>>> from ansys.mechanical.core import launch_mechanical
>>> mechanical = launch_mechanical()
>>> mechanical

Ansys Mechanical [Ansys Mechanical Enterprise]
Product Version:242
Software build date: 06/03/2024 14:47:58

Launch Mechanical from the command line#

The ansys-mechanical utility is installed automatically with PyMechanical, and can be used to run Mechanical from the command line. To obtain help on usage, type the following command:

$ ansys-mechanical --help

Usage: ansys-mechanical [OPTIONS]

    CLI tool to run mechanical.

    USAGE:

    The following example demonstrates the main use of this tool:

        $ ansys-mechanical -r 242 -g

        Starting Ansys Mechanical version 2024R1 in graphical mode...

Options:
    -h, --help                 Show this message and exit.
    -p, --project-file TEXT    Opens Mechanical project file (.mechdb). Cannot
                                be mixed with -i
    --private-appdata         Make the appdata folder private. This enables you
                                to run parallel instances of Mechanical.
    --port INTEGER             Start mechanical in server mode with the given
                                port number
    -i, --input-script TEXT    Name of the input Python script. Cannot be mixed
                                with -p
    --features TEXT            Beta feature flags to set, as a semicolon
                                delimited list. Options: ['MultistageHarmonic',
                                'ThermalShells']
    --exit                     Exit the application after running an input
                                script. You can only use this command with
                                --input-script argument (-i). The command
                                defaults to true you are not running the
                                application in graphical mode. The ``exit``
                                command is only supported in version 2024 R1 or
                                later.
    -s, --show-welcome-screen  Show the welcome screen. You use this screen to
                                open a file. This argument only affects the
                                application when in graphical mode.
    --debug                    Show a debug dialog window at the start of the
                                process.
    -r, --revision INTEGER     Ansys Revision number, e.g. "242" or "241". If
                                none is specified, uses the default from ansys-
                                tools-path
    -g, --graphical            Graphical mode

...

You can launch Mechanical in server mode from the command line and then manually connect to the server. Use the port argument to select the port.

ansys-mechanical --port 10000

Connect to a Mechanical session#

You can connect to a Mechanical session from the same host or from an external host.

Assuming that Mechanical is running locally at the default IP address (127.0.0.1) on the default port (10000), you would use this code to connect to it with this code:

from ansys.mechanical.core import Mechanical

mechanical = Mechanical()

Now assume that a remote instance of Mechanical has been started in server mode. To connect to the computer on your local area network that is running Mechanical, you can use either an IP address and port or a hostname and port.

IP address and port

Assume that Mechanical is running remotely at IP address 192.168.0.1 on port 10000.

You would connect to it with this code:

mechanical = Mechanical("192.168.0.1", port=10000)

Hostname and port

Assume that Mechanical is running remotely at hostname myremotemachine on port 10000.

You would connect to it with this code:

mechanical = Mechanical("myremotemachine", port=10000)

Launching issues#

For any number of reasons, launching Mechanical can fail. Some approaches follow for debugging launch failures.

Manually set the location of the executable file#

If you have a non-standard installation of Mechanical, PyMechanical might not be able to find your installation. In this case, you should manually set the location of your Mechanical executable file as the first parameter for the launch_mechanical() method.

On Windows

from ansys.mechanical.core import launch_mechanical

exec_loc = "C:/Program Files/ANSYS Inc/v242/aisol/bin/winx64/AnsysWBU.exe"
mechanical = launch_mechanical(exec_loc)

On Linux

from ansys.mechanical.core import launch_mechanical

exec_loc = "/usr/ansys_inc/v242/aisol/.workbench"
mechanical = launch_mechanical(exec_loc)

If, when using the launch_mechanical() method, Mechanical still fails to launch or hangs while launching, pass the verbose_mechanical=True parameter. This prints the output of Mechanical in the Python console. You can then use this output to debug why Mechanical isn’t launching.

Note

On Windows, output is limited because of the way Mechanical launches.

Debug from the command line#

You may need to run the launch command from the command line to debug why Mechanical is not launching. running the launch command from the command line.

Open a terminal and run the following command:

ansys-mechanical -g --port 10000

If the preceding command for your operating system doesn’t launch Mechanical, you might have a variety of issues, including:

  • License server setup

  • Running behind a VPN

  • Missing dependencies

Embed a Mechanical instance#

The instructions for embedding a Mechanical instance are different on Windows and Linux. While the Python code is the same in both cases, Linux requires some additional environment variables.

Python code#

>>> from ansys.mechanical.core import App
>>> mechanical = App()
>>> mechanical
Ansys Mechanical [Ansys Mechanical Enterprise]
Product Version:242
Software build date: 06/03/2024 14:47:58

Additional information for Linux#

Starting with 2023 R2, it is possible to embed an instance of Mechanical on Linux. However, because of differences in how Mechanical works on Linux, you cannot simply run Python as usual. On Linux, certain environment variables must be set for the Python process before it starts. You can set up these environment variables using the mechanical-env script which is part of PyMechanical

$ mechanical-env python

Licensing issues#

PADT has an Ansys product section. Posts about licensing are common.

If you are responsible for maintaining an Ansys license or have a personal installation of Ansys, you likely can access the Licensing section of the Ansys Help, where you can view or download the Ansys, Inc. Licensing Guide for comprehensive licensing information.

VPN issues#

Sometimes, Mechanical has issues starting when VPN software is running. For more information, access the Mechanical Users Guide in the Ansys Help.