launcher#

Provides a module for launching CFX.

This module supports both starting CFX locally and connecting to a remote instance with gRPC.

Functions:

`connect_to_cfx`([ip, port, address, ...])	Connect to an existing CFX server instance.
`create_launcher`([cfx_launch_mode])	Use a factory function to create a launcher for supported launch modes.
`launch_cfx`([product_version, ...])	Launch CFX locally in server mode or connect to a running CFX server instance.

ansys.cfx.core.launcher.launcher.connect_to_cfx(ip: str | None = None, port: int | None = None, address: str | None = None, cleanup_on_exit: bool = False, start_transcript: bool = False, server_info_file_name: str | None = None, password: str | None = None, allow_remote_host: bool = False, certificates_folder: str | None = None, insecure_mode: bool = False, start_watchdog: bool | None = None) → PreProcessing | Solver | PostProcessing#

Connect to an existing CFX server instance.

Parameters:

ipstr, default: None: IP address for connecting to an existing CFX instance. When None, the IP address defaults to "127.0.0.1". You can also use the PYCFX_CFX_IP=<ip> environment variable to set this parameter. The explicit value of the ip parameter takes precedence over the PYCFX_CFX_IP=<ip> environment variable.
portint, default: None: Port to listen on for an existing CFX instance. You can also use the PYCFX_CFX_PORT=<port> environment variable to set a default value. The explicit value of the port parameter takes precedence over the PYCFX_CFX_PORT=<port> environment variable.
addressstr, default: None: Address to connect to an existing CFX instance.
cleanup_on_exitbool, default: False: Whether to shut down the connected CFX session when PyCFX is exited, or if the exit() method is called on the session instance, or if the session instance becomes unreferenced.
start_transcriptbool, default: False: Whether to start streaming the CFX transcript in the client. You can stop and start the streaming of the CFX transcript subsequently using the transcript.start() and transcript.stop() methods on the session object.
server_info_file_name: str, default: None: Path to the server information file written out by CFX server. PyCFX uses the connection information in the file to connect to a running CFX session.
passwordstr, default: None: Password to connect to an existing CFX instance.
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.
start_watchdog: bool, default: None: When cleanup_on_exit is True, start_watchdog defaults to True, which means an independent watchdog process is run to ensure that any local CFX connections are properly closed (or terminated if frozen) when the Python process ends.

Returns:

Union [PreProcessing, Solver, PostProcessing]: Session object.

Raises:

ValueError: Raised when neither certificates_folder nor insecure_mode are set while allow_remote_host is True. Raised when both certificates_folder and insecure_mode are set simultaneously. Raised when certificates_folder is set but allow_remote_host is False. Raised when insecure_mode is set but allow_remote_host is False.

ansys.cfx.core.launcher.launcher.create_launcher(cfx_launch_mode: LaunchMode = None, **kwargs)#

Use a factory function to create a launcher for supported launch modes.

Parameters:

cfx_launch_mode: LaunchMode: Supported CFX launch modes. Options are "LaunchMode.CONTAINER" and "LaunchMode.STANDALONE".
kwargsAny: Keyword arguments.

Returns:

launcher: Union[DockerLauncher, StandaloneLauncher]: Session launcher.

Raises:

DisallowedValuesError: If an unknown CFX launch mode is passed.
NotImplementedError: If an unimplemented CFX launch mode is passed.

Launch CFX locally in server mode or connect to a running CFX server instance.

Parameters:

product_versionstr, default: None: Version of Ansys CFX to launch. The string must be in a format like "25.2.0" (for 2025 R2), matching the documented version format in the CFXVersion class. The default is None, in which case the newest installed version is used.
journal_file_namesstr | list[str], default: None: String path to a CFX journal file or a list of such paths. CFX executes the journals.
start_timeoutint, default: None: Maximum allowable time in seconds for connecting to the CFX server. The default is None, in which case 60 seconds is used if CFX is launched outside a Slurm environment. No timeout occurs if CFX is launched within a Slurm environment.
additional_argumentsstr, default: “”: Additional arguments to send to CFX as a string in the same format they are normally passed to CFX on the command line.
envdict, default: None: Mapping to modify environment variables in CFX.
start_containerbool, default: None: Whether to launch a CFX Docker container image. For more information about containers, see cfx_container.
container_dictdict, default: None: Dictionary for CFX Docker container configuration. If specified, setting start_container = True is redundant. CFX launches inside a Docker container using the configuration changes specified. See also cfx_container.
dry_runbool, default: False: Whether to dry run a container start. If True, CFX is not launched but the configuration information that would be used is printed as if CFX is being launched. If dry running a container start, the launch_cfx() method returns the configured container_dict.
cleanup_on_exitbool, default: True: Whether to shut down the connected CFX session when PyCFX is exited, or the exit() method is called on the session instance, or if the session instance becomes unreferenced.
start_transcriptbool, default: False: Whether to start streaming the CFX transcript in the client. You can stop and start the streaming of the CFX transcript subsequently using the transcript.start() and transcript.stop() methods on the session object.
ui_modeUIMode or str, default: None: CFX user interface mode. Options are either the values of the UIMode enum or any of "no_gui", "hidden_gui", or "gui". When None, UIMode.HIDDEN_GUI is used.
case_file_namestr, default: None: Name of the case file to read into a CFX-Pre session.
run_directorystr, default: None: Name of the run directory to monitor with a CFX-Solver or CFD-Post session.
results_file_namestr, default: None: Name of the results file to read into a CFD-Post session or start a CFX-Solver session.
solver_input_file_namestr, default: None: Name of the solver input file to start a CFX-Solver session.
modestr, default: None: Launch mode of CFX to point to a specific session type. Options are "pre-processing", "solver", and "post-processing".
cwdstr, default: None: Working directory for the CFX client.
topybool or str, default: None: Boolean flag to write the equivalent Python journals from the journals passed. This parameter can optionally take the file name of a new Python journal file.
start_watchdogbool, default: None: When cleanup_on_exit is True, start_watchdog defaults to True, which means an independent watchdog process is run to ensure that any local GUI-less CFX sessions started by PyCFX are properly closed (or killed if frozen) when the current Python process ends.
scheduler_optionsdict, default: None: Dictionary containing scheduler (such as Slurm scheduler) options.
file_transfer_servicedefault: None: File transfer service. Uploads or downloads files to or from the server.
kwargsAny: Keyword arguments.

Returns:

Union [PreProcessing, Solver, PostProcessing, dict]: Session object or configuration dictionary if dry_run = True.

Raises:

UnexpectedKeywordArgument: If an unexpected keyword argument is provided.
DockerContainerLaunchNotSupported: If a CFX Docker container launch is not supported.

Notes

Job scheduler environments such as SLURM, LSF, and PBS allocate resources and compute nodes. The allocated machines and core counts are queried from the scheduler environment and passed to CFX.