cfx_connection

Module for CFX connection functionality.

Classes:

CFXConnection([ip, port, address, password, ...])	Encapsulates a CFX connection.
CFXConnectionProperties([ip, port, address, ...])	Stores CFX connection properties, including connection IP address, port, UDS address, and password; CFX Engine working directory, process ID, and hostname; and whether CFX was launched in a Docker container.
ErrorState([name, details])	Indicates the error state of the connected CFX client.
MonitorThread()	Monitors a CFX session.

Exceptions:

InsecureGrpcWarning	Raised when the gRPC connection is insecure.
PortNotProvided()	Raised when the port is not provided.
UnsupportedRemoteCFXInstance()	Raised when the wait_process_finished method does not support a remote CFX session.
WaitTypeError()	Raised when invalid wait type is provided.

Functions:

get_container(container_id_or_name)

Get the Docker container object.

class ansys.cfx.core.cfx_connection.CFXConnection(ip: str | None = None, port: int | None = None, address: str | None = None, password: str | None = None, channel: Channel | None = None, allow_remote_host: bool = False, certificates_folder: str | None = None, insecure_mode: bool = False, cleanup_on_exit: bool = True, start_transcript: bool = False, remote_instance: Instance | None = None, launcher_args: Dict[str, Any] | None = None, inside_container: bool | None = None)

Bases: object

Encapsulates a CFX connection.

Methods

exit()

Close the CFX connection and exit CFX.

Methods:

__init__([ip, port, address, password, ...])	Initialize a session.
create_grpc_service(service, *args)	Create a gRPC service.
exit([timeout, timeout_force, wait])	Close the CFX connection and exit CFX.
force_exit()	Terminate the CFX client immediately, which results in losing unsaved progress and data.
register_finalizer_cb(cb)	Register a callback to run with the finalizer.
wait_process_finished([wait])	Return True if local CFX processes have finished, False if they are still running when wait limit (default 60 seconds) is reached.

Attributes:

cfx_build_info

CFX build information.

__init__(ip: str | None = None, port: int | None = None, address: str | None = None, password: str | None = None, channel: Channel | None = None, allow_remote_host: bool = False, certificates_folder: str | None = None, insecure_mode: bool = False, cleanup_on_exit: bool = True, start_transcript: bool = False, remote_instance: Instance | None = None, launcher_args: Dict[str, Any] | None = None, inside_container: bool | None = None)

Initialize a session.

Parameters:

ipstr, default: None

IP address to connect to an existing CFX instance. This parameter is used only when channel is None. When this parameter is None, "127.0.0.1" is used. The IP address can also be set by the PYCFX_CFX_IP=<ip> environment variable.

portint, default: None

Port to connect to an existing CFX instance. This parameter is used only when channel is None. The port can also be set by the PYCFX_CFX_PORT=<port> environment variable.

addressstr, default: None

Address to connect to an existing CFX instance.

passwordstr, default: None

Password to connect to an existing CFX instance.

channelgrpc.Channel, default: None

gRPC channel to use to connect to an existing CFX instance. The ip and port parameters are ignored when a gRPC channel is specified.

allow_remote_hostbool, default: False

Whether to allow connecting to a remote CFX instance.

certificates_folderstr, default: None

Path to the folder containing TLS certificates for CFX’s gRPC server.

insecure_modebool, default: False

Whether to connect CFX’s gRPC server in insecure mode without TLS. This mode is not recommended. For more information on the implications and usage of insecure mode, see the CFX documentation.

cleanup_on_exitbool, default: True

Whether to shut down the connected CFX session when PyCFX is exited or the exit() function is called on the session instance.

start_transcriptbool, default: False

Whether to start the CFX transcript in the client. The CFX transcript can be started and stopped subsequently using method calls on the session object.

remote_instanceansys.platform.instancemanagement.Instance

Corresponding remote instance when CFX is launched through PyPIM. This instance is deleted when calling the Session.exit() function.

inside_container: bool, default: None

Whether the CFX session that is being connected to is running inside a Docker container.

Raises:

PortNotProvided

If port is not provided.

property cfx_build_info: str

CFX build information.

create_grpc_service(service, *args)

Create a gRPC service.

Parameters:

serviceAny

Service class.

argsAny

Additional arguments.

Returns:

Any

Service object.

exit(timeout: float | None = None, timeout_force: bool = True, wait: float | int | bool | None = False) → None

Close the CFX connection and exit CFX.

Parameters:

timeoutfloat, default: None

Time in seconds before considering that the exit request has timed out. If omitted or specified as None, the request does not time out and locks up the interpreter while waiting for a response. The request returns earlier if it succeeds earlier.

timeout_forcebool, default: True

Whether to attempt to terminate the CFX process if the exit request reached timeout. If no timeout is set, this option is ignored. Executes the force_exit() or force_exit_container() function to terminate the CFX process, depending on how CFX was launched.

waitfloat, int or bool, default: False

Whether to wait for local CFX processes to finish completely before proceeding. If omitted or specified as False, the request proceeds as usual without waiting for the CFX processes to finish. If this parameter is set to True the request waits for up to 60 seconds by default. The wait limit can be specified as a float or integer value. If the wait limit is reached, the request forcefully terminate the CFX process. If it is set to wait, it returns as soon as the processes completely finishes. It does not work for the remote CFX processes.

Notes

The PYCFX_TIMEOUT_FORCE_EXIT environment variable can also be used to specify the number of seconds and alter the default timeout value. Setting this environment variable to a non-number value, such as OFF, returns this function to the default behavior. Note that the environment variable is ignored if a timeout is specified when calling this function.

Examples

>>> import ansys.cfx.core as pycfx
>>> session = pycfx.launch_cfx()
>>> session.exit()

force_exit()

Terminate the CFX client immediately, which results in losing unsaved progress and data.

Notes

If the CFX session is responsive, using the exit() function is preferred.

Examples

>>> import ansys.cfx.core as pycfx
>>> session = pycfx.launch_cfx()
>>> session.force_exit()

register_finalizer_cb(cb)

Register a callback to run with the finalizer.

wait_process_finished(wait: float | int | bool = 60)

Return True if local CFX processes have finished, False if they are still running when wait limit (default 60 seconds) is reached. Immediately cancels and returns None if wait is set to False.

Parameters:

waitfloat, int or bool, default: 60

How long to wait for processes to finish before returning. The default is 60 seconds. This parameter can also be set to True, which results in waiting indefinitely.

Raises:

UnsupportedRemoteCFXInstance

If current CFX instance is running remotely.

WaitTypeError

If wait is specified improperly.

class ansys.cfx.core.cfx_connection.CFXConnectionProperties(ip: str | None = None, port: int | None = None, address: str | None = None, password: str | None = None, engine_pwd: str | None = None, engine_pid: int | None = None, engine_host: str | None = None, cfx_host_pid: int | None = None, inside_container: bool | Container | None = None)

Bases: object

Stores CFX connection properties, including connection IP address, port, UDS address, and password; CFX Engine working directory, process ID, and hostname; and whether CFX was launched in a Docker container.

Examples

These properties are also available through the session object and can be accessed:

>>> import ansys.cfx.core as pycfx
>>> session = pycfx.launch_cfx()
>>> session.connection_properties.list_names()
['ip', 'port', 'address', 'password', 'engine_pwd', 'engine_pid', 'engine_host', 'cfx_host_pid', 'inside_container']
>>> session.connection_properties.ip
'localhost'

Methods:

__init__([ip, port, address, password, ...])
list_names()	Get a list of all property names.
list_values()	Get a dictionary with all property names and values.

Attributes:

address	The UDS address of the connected CFX session.
cfx_host_pid	The process ID of the CFX engine (same as engine_pid).
engine_host	The hostname of the machine where the CFX engine is running.
engine_pid	The process ID of the CFX engine (same as cfx_host_pid).
engine_pwd	The CFX engine working directory.
inside_container	Whether the connected CFX session is running inside a Docker container.
ip	The IP address of the connected CFX session.
password	The password used to connect to the CFX session.
port	The port of the connected CFX session.

__init__(ip: str | None = None, port: int | None = None, address: str | None = None, password: str | None = None, engine_pwd: str | None = None, engine_pid: int | None = None, engine_host: str | None = None, cfx_host_pid: int | None = None, inside_container: bool | Container | None = None) → None

address: str | None = None

The UDS address of the connected CFX session.

cfx_host_pid: int | None = None

The process ID of the CFX engine (same as engine_pid).

engine_host: str | None = None

The hostname of the machine where the CFX engine is running.

engine_pid: int | None = None

The process ID of the CFX engine (same as cfx_host_pid).

engine_pwd: str | None = None

The CFX engine working directory.

inside_container: bool | Container | None = None

Whether the connected CFX session is running inside a Docker container.

ip: str | None = None

The IP address of the connected CFX session.

list_names() → list

Get a list of all property names.

list_values() → dict

Get a dictionary with all property names and values.

password: str | None = None

The password used to connect to the CFX session.

port: int | None = None

The port of the connected CFX session.

class ansys.cfx.core.cfx_connection.ErrorState(name: str = '', details: str = '')

Bases: object

Indicates the error state of the connected CFX client.

Examples

>>> import ansys.cfx.core as pycfx
>>> session = pycfx.launch_cfx()
>>> session._cfx_connection._error_state.set("test", "test details")
>>> session._cfx_connection._error_state.name
'test'
>>> session._cfx_connection._error_state.details
'test details'
>>> session._cfx_connection._error_state.clear()
>>> session._cfx_connection._error_state.name
''

Methods:

__init__([name, details])	Initialize the error state object.
clear()	Clear the current error state, emptying the error name and details properties.
set(name, details)	Set the error state name and details to new values.

Attributes:

details	Additional details of the error state.
name	Name of the error state.

__init__(name: str = '', details: str = '')

Initialize the error state object.

Parameters:

namestr

Name of the error state, which is by default an empty string, indicating no errors.

detailsstr

Additional details of the error, which is by default an empty string.

clear()

Clear the current error state, emptying the error name and details properties.

property details

Additional details of the error state.

property name

Name of the error state.

set(name: str, details: str)

Set the error state name and details to new values.

exception ansys.cfx.core.cfx_connection.InsecureGrpcWarning

Bases: Warning

Raised when the gRPC connection is insecure.

class ansys.cfx.core.cfx_connection.MonitorThread

Bases: Thread

Monitors a CFX session.

A daemon thread that ensures cleanup of session objects and shut down of non-daemon threads.

Attributes:

cbsList[Callable]

Cleanup and shutdown functions.

Methods:

__init__()	Initialize an instance of the MonitorThread class.
run()	Run the monitor thread.

__init__()

Initialize an instance of the MonitorThread class.

run() → None

Run the monitor thread.

exception ansys.cfx.core.cfx_connection.PortNotProvided

Bases: ValueError

Raised when the port is not provided.

Methods:

__init__()

__init__()

exception ansys.cfx.core.cfx_connection.UnsupportedRemoteCFXInstance

Bases: ValueError

Raised when the wait_process_finished method does not support a remote CFX session.

Methods:

__init__()

__init__()

exception ansys.cfx.core.cfx_connection.WaitTypeError

Bases: TypeError

Raised when invalid wait type is provided.

Methods:

__init__()

__init__()

ansys.cfx.core.cfx_connection.get_container(container_id_or_name: str) → bool | Container | None

Get the Docker container object.

Returns:

Union[bool, Container, None]

If the system is not correctly set up to run Docker containers, returns None. If the container was not found, returns False. If the container is found, returns the associated Docker container object.

Notes

See Docker container for more information.