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:
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()
Alternatively, you can use the connect_to_mechanical() for same functionality.
from ansys.mechanical.core import connect_to_mechanical
mechanical = connect_to_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)
or
mechanical = connect_to_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)
or
mechanical = connect_to_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.