The mechanical.py module#

Summary#

Mechanical

Connects to a gRPC Mechanical server and allows commands to be passed.

setup_logger

Initialize the logger for the given mechanical instance.

suppress_logging

Decorate a function to suppress the logging for a Mechanical instance.

port_in_use

Check whether a port is in use at the given host.

check_ports

Check the state of ports in a port range.

close_all_local_instances

Close all Mechanical instances within a port range.

create_ip_file

Create the mylocal.ip file needed to change the IP address of the gRPC server.

get_mechanical_path

Get path.

check_valid_mechanical

Change to see if the default Mechanical path is valid.

change_default_mechanical_path

Change default path.

save_mechanical_path

Save path.

get_start_instance

Check if the PYMECHANICAL_START_INSTANCE environment variable exists and is valid.

launch_grpc

Start Mechanical locally in gRPC mode.

launch_remote_mechanical

Start Mechanical remotely using the Product Instance Management (PIM) API.

launch_mechanical

Start Mechanical locally.

MAX_MESSAGE_LENGTH

Default message length.

DEFAULT_CHUNK_SIZE

Default chunk size.

DEFAULT_FILE_CHUNK_SIZE

Default file chunk size.

LOCALHOST

Localhost address.

MECHANICAL_DEFAULT_PORT

Default Mechanical port.

GALLERY_INSTANCE

List of gallery instances.

Description#

Connect to Mechanical gRPC server and issues commands.

Module detail#

mechanical.setup_logger(loglevel='INFO', log_file=True, mechanical_instance=None)#

Initialize the logger for the given mechanical instance.

mechanical.suppress_logging(func)#

Decorate a function to suppress the logging for a Mechanical instance.

mechanical.port_in_use(port, host=LOCALHOST)#

Check whether a port is in use at the given host.

You must actually bind the address. Just checking if you can create a socket is insufficient because it is possible to run into permission errors like:

An attempt was made to access a socket in a way forbidden by its
access permissions.
mechanical.check_ports(port_range, ip='localhost')#

Check the state of ports in a port range.

mechanical.close_all_local_instances(port_range=None, use_thread=True)#

Close all Mechanical instances within a port range.

You can use this method when cleaning up from a failed pool or batch run.

Parameters:
port_rangelist, optional

List of a range of ports to use when cleaning up Mechanical. The default is None, in which case the ports managed by PyMechanical are used.

use_threadbool, optional

Whether to use threads to close the Mechanical instances. The default is True. So this call will return immediately.

Examples

Close all Mechanical instances connected on local ports.

>>> import ansys.mechanical.core as pymechanical
>>> pymechanical.close_all_local_instances()
mechanical.create_ip_file(ip, path)#

Create the mylocal.ip file needed to change the IP address of the gRPC server.

mechanical.get_mechanical_path(allow_input=True)#

Get path.

Deprecated - use ansys.tools.path.get_mechanical_path instead

mechanical.check_valid_mechanical()#

Change to see if the default Mechanical path is valid.

mechanical.change_default_mechanical_path(exe_loc)#

Change default path.

Deprecated - use ansys.tools.path.change_default_mechanical_path instead.

mechanical.save_mechanical_path(exe_loc=None)#

Save path.

Deprecated - use ansys.tools.path.save_mechanical_path instead.

mechanical.get_start_instance(start_instance_default=True)#

Check if the PYMECHANICAL_START_INSTANCE environment variable exists and is valid.

Parameters:
start_instance_defaultbool, optional

Value to return when PYMECHANICAL_START_INSTANCE is unset.

Returns:
bool

True when the PYMECHANICAL_START_INSTANCE environment variable exists and is valid, False when this environment variable does not exist or is not valid. If it is unset, start_instance_default is returned.

Raises:
OSError

Raised when PYMECHANICAL_START_INSTANCE is not either True or False (case independent).

mechanical.launch_grpc(exec_file='', batch=True, port=MECHANICAL_DEFAULT_PORT, additional_switches=None, additional_envs=None, verbose=False) int#

Start Mechanical locally in gRPC mode.

Parameters:
exec_filestr, optional

Path for the Mechanical executable file. The default is None, in which case the cached location is used.

batchbool, optional

Whether to launch Mechanical in batch mode. The default is True. When False, Mechanical is launched in UI mode.

portint, optional

Port to launch the Mechanical instance on. The default is MECHANICAL_DEFAULT_PORT. The final port is the first port available after (or including) this port.

additional_switcheslist, optional

List of additional arguments to pass. The default is None.

additional_envsdictionary, optional

Dictionary of additional environment variables to pass. The default is None.

verbosebool, optional

Whether to print all output when launching and running Mechanical. The default is False. Printing all output is not recommended unless you are debugging the startup of Mechanical.

Returns:
int

Port number that the Mechanical instance started on.

Notes

If PYMECHANICAL_START_INSTANCE is set to FALSE, the launch_mechanical method looks for an existing instance of Mechanical at PYMECHANICAL_IP on port PYMECHANICAL_PORT, with default to 127.0.0.1 and 10000 if unset. This is typically used for automated documentation and testing.

Examples

Launch Mechanical using the default configuration.

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

Launch Mechanical using a specified executable file.

>>> exec_file_path = 'C:/Program Files/ANSYS Inc/v231/aisol/bin/win64/AnsysWBU.exe'
>>> mechanical = launch_mechanical(exec_file_path)
mechanical.launch_remote_mechanical(version=None)#

Start Mechanical remotely using the Product Instance Management (PIM) API.

When calling this method, you must ensure that you are in an environment where PyPIM is configured. You can use the pypim.is_configured method to verify that PyPIM is configured.

Parameters:
versionstr, optional

Mechanical version to run in the three-digit format. For example, "231" to run 2023 R1. The default is None, in which case the server runs the latest installed version.

Returns:
Tuple containing channel, remote_instance.
mechanical.launch_mechanical(allow_input=True, exec_file=None, batch=True, loglevel='ERROR', log_file=False, log_mechanical=None, additional_switches=None, additional_envs=None, start_timeout=120, port=None, ip=None, start_instance=None, verbose_mechanical=False, clear_on_connect=False, cleanup_on_exit=True, version=None, keep_connection_alive=True) Mechanical#

Start Mechanical locally.

Parameters:
allow_input: bool, optional

Whether to allow user input when discovering the path to the Mechanical executable file.

exec_filestr, optional

Path for the Mechanical executable file. The default is None, in which case the cached location is used. If PyPIM is configured and this parameter is set to None, PyPIM launches Mechanical using its version parameter.

batchbool, optional

Whether to launch Mechanical in batch mode. The default is True. When False, Mechanical launches in UI mode.

loglevelstr, optional

Level of messages to print to the console. Options are:

  • "WARNING": Prints only Ansys warning messages.

  • "ERROR": Prints only Ansys error messages.

  • "INFO": Prints all Ansys messages.

The default is WARNING.

log_filebool, optional

Whether to copy the messages to a file named logs.log, which is located where the Python script is executed. The default is False.

log_mechanicalstr, optional

Path to the output file on the local disk to write every script command to. The default is None. However, you might set "log_mechanical='pymechanical_log.txt'" to write all commands that are sent to Mechanical via PyMechanical to this file. You can then use these commands to run a script within Mechanical without PyMechanical.

additional_switcheslist, optional

Additional switches for Mechanical. The default is None.

additional_envsdictionary, optional

Dictionary of additional environment variables to pass. The default is None.

start_timeoutfloat, optional

Maximum allowable time in seconds to connect to the Mechanical server. The default is 120.

portint, optional

Port to launch the Mechanical gRPC server on. The default is None, in which case 10000 is used. The final port is the first port available after (or including) this port. You can override the default behavior of this parameter with the PYMECHANICAL_PORT= PORT> environment variable.

ipstr, optional

IP address to use only when start_instance is False. The default is None, in which case "127.0.0.1" is used. If you provide an IP address, start_instance is set to False. A host name can be provided as an alternative to an IP address.

start_instancebool, optional

Whether to launch and connect to a new Mechanical instance. The default is None, in which case an attempt is made to connect to an existing Mechanical instance at the given ip and port parameters, which have defaults of "127.0.0.1" and 10000 respectively. When True, a local instance of Mechanical is launched. You can override the default behavior of this parameter with the PYMECHANICAL_START_INSTANCE=FALSE environment variable.

verbose_mechanicalbool, optional

Whether to enable printing of all output when launching and running a Mechanical instance. The default is False. This parameter should be set to True for debugging only as output can be tracked within PyMechanical.

clear_on_connectbool, optional

When start_instance is False, whether to clear the environment when connecting to Mechanical. The default is False. When True, a fresh environment is provided when you connect to Mechanical.

cleanup_on_exitbool, optional

Whether to exit Mechanical when Python exits. The default is True. When False, Mechanical is not exited when the garbage for this Mechanical instance is collected.

versionstr, optional

Mechanical version to run in the three-digit format. For example, "231" for 2023 R1. The default is None, in which case the server runs the latest installed version. If PyPIM is configured and exce_file=None, PyPIM launches Mechanical using its version parameter.

keep_connection_alivebool, optional

Whether to keep the gRPC connection alive by running a background thread and making dummy calls for remote connections. The default is True.

Returns:
ansys.mechanical.core.mechanical.Mechanical

Instance of Mechanical.

Notes

If the environment is configured to use PyPIM and start_instance=True, then starting the instance is delegated to PyPIM. In this case, most of the preceding parameters are ignored because the server-side configuration is used.

Examples

Launch Mechanical.

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

Launch Mechanical using a specified executable file.

>>> exec_file_path = 'C:/Program Files/ANSYS Inc/v231/aisol/bin/win64/AnsysWBU.exe'
>>> mech = launch_mechanical(exec_file_path)

Connect to an existing Mechanical instance at IP address 192.168.1.30 on port 50001.

>>> mech = launch_mechanical(start_instance=False, ip='192.168.1.30', port=50001)
mechanical.MAX_MESSAGE_LENGTH#

Default message length.

mechanical.DEFAULT_CHUNK_SIZE#

Default chunk size.

mechanical.DEFAULT_FILE_CHUNK_SIZE#

Default file chunk size.

mechanical.LOCALHOST = '127.0.0.1'#

Localhost address.

mechanical.MECHANICAL_DEFAULT_PORT = 10000#

Default Mechanical port.

mechanical.GALLERY_INSTANCE = [None]#

List of gallery instances.

mechanical.client_to_server_loglevel#