cfx_container#

Provides a module for launching and configuring local CFX Docker container runs.

Notes#

For configuration information, see the configure_container_dict() function. For a list of additional Docker container run configuration options that can also be specified through the container_dict argument for the launch_cfx() function, see Docker run in the Docker SDK for Python containers documentation

For the CFX Docker container to be able to find license information, the license file or server needs to be specified through the ANSYSLMD_LICENSE_FILE environment variable, or the license_server argument for the container_dict (see configure_container_dict()).

Examples#

Launch a CFX Docker container with the system default configuration:

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

Launch with a custom configuration, using cfx_image and host_mount_path, which are arguments for the configure_container_dict() function. auto_remove is an argument for Docker run:

>>> import ansys.cfx.core as pycfx
>>> custom_config = {}
>>> custom_config.update(cfx_image='custom_cfx:v25.2.3', host_mount_path='/testing',
...   auto_remove=False)
>>> session = pycfx.launch_cfx(container_dict=custom_config)

Get the default CFX Docker container configuration and then launch with the customized configuration:

>>> import ansys.cfx.core as pycfx
>>> config_dict = pycfx.launch_cfx(start_container=True, dry_run=True)
Docker container run configuration information:
config_dict =
{'auto_remove': True,
 'command': ['-py', '-sifile /mnt/pycfx/serverinfo-lpqsdldw.txt'],
 'detach': True,
 'environment': {'ANSYSLMD_LICENSE_FILE': '2048@licenseserver.com',
                 'REMOTING_PORTS': '54000/portspan=2'},
 'cfx_image': 'ghcr.io/ansys/pycfx:v25.2.3',
 'labels': {'test_name': 'none'},
 'ports': {'54000': 54000},
 'volumes': ['/home/user/.local/share/ansys_cfx_core/examples:/mnt/pycfx'],
 'working_dir': '/mnt/pycfx'}
>>> config_dict.update(image_name='custom_cfx', image_tag='v25.2.3', mem_limit='1g')
>>> session = pycfx.launch_cfx(container_dict=config_dict)

Exceptions:

CFXCommandNotSpecified()

Raised when a CFX session command is not specified.

CFXImageNameTagNotSpecified()

Raised when the CFX image name or image tag is not specified.

LicenseServerNotSpecified()

Raised when the license server is not specified.

ServerInfoFileError()

Raised when the server information file is not given properly.

Functions:

configure_container_dict(args[, ...])

Parse the following parameters and set up the container configuration file.

extract_mount_paths(container_dict)

Extract host and container mount paths from a container configuration dictionary.

replace_container_path_with_host_path(line, ...)

Replace the first occurrence of a container path in the given line with its corresponding host path.

replace_host_path_with_container_path(line, ...)

Replace the first occurrence of a host path in the given line with its corresponding container path.

start_cfx_container(args[, container_dict])

Start a CFX container.
exception ansys.cfx.core.launcher.cfx_container.CFXCommandNotSpecified#

Bases: ValueError

Raised when a CFX session command is not specified.

Methods:

__init__()

__init__()#
exception ansys.cfx.core.launcher.cfx_container.CFXImageNameTagNotSpecified#

Bases: ValueError

Raised when the CFX image name or image tag is not specified.

Methods:

__init__()

__init__()#
exception ansys.cfx.core.launcher.cfx_container.LicenseServerNotSpecified#

Bases: KeyError

Raised when the license server is not specified.

Methods:

__init__()

__init__()#
exception ansys.cfx.core.launcher.cfx_container.ServerInfoFileError#

Bases: ValueError

Raised when the server information file is not given properly.

Methods:

__init__()

__init__()#
ansys.cfx.core.launcher.cfx_container.configure_container_dict(args: List[str], host_mount_path: str | Path | None = None, container_mount_path: str | Path | None = None, timeout: int = 240, port: int | None = None, license_server: str | None = None, container_server_info_file: str | Path | None = None, remove_server_info_file: bool = True, cfx_image: str | None = None, image_name: str | None = None, image_tag: str | None = None, has_remote_server: bool = True, **container_dict) → tuple[dict, int, int, Path, bool]#

Parse the following parameters and set up the container configuration file.

Parameters:
argsList[str]

List of CFX launch arguments.

host_mount_pathUnion[str, Path], default: None

Existing path in the host operating system that is available inside the container.

container_mount_pathUnion[str, Path], default: None

Path inside the container where the host mount path is mounted to.

timeoutint, default: None

Time limit in seconds for the CFX container to start. When None, 30 seconds is used.

portint, default: None

Port for CFX container to use.

license_serverstr, default: None

License server for Ansys CFX to use.

container_server_info_fileUnion[str, Path], default: None

Name of the server information file for CFX to write on the host_mount_path argument.

remove_server_info_filebool, default: True

Whether to automatically delete the server information file after PyCFX has finished using it.

has_remote_serverbool, default: True

Whether to create a server information file for server and client communication setup.

cfx_imagestr, default: None

Specifies full image name for Docker container run, with the format "image_name:image_tag". The image_tag and image_name parameters are ignored if the cfx_image parameter has been specified.

image_namestr, default: None

Ignored if the cfx_image parameter has been specified.

image_tagstr, default: None

Ignored if the cfx_image parameter has been specified.

**container_dict

Additional keyword arguments that can be specified. They are treated as Docker container run options to be passed directly to the Docker run execution. See the following examples and Docker run documentation.

Returns:
cfx_imagestr
container_dictdict
timeoutint
portint
host_server_info_filePath
remove_server_info_file: bool
Raises:
LicenseServerNotSpecified

If license server is not specified through an environment variable or in container_dict.

ServerInfoFileError

If server information file is specified through both a command-line argument inside container_dict and the container_server_info_file parameter.

CFXImageNameTagNotSpecified

If cfx_image or image_tag and image_name are not specified.

CFXCommandNotSpecified

If cfx_cmd is not specified.

Notes

This function should usually not be called directly. It is automatically used by the launch_cfx() function.

For a list of additional Docker container run configuration options that can also be specified using container_dict, see Docker run documentation.

See also the start_cfx_container() function.

ansys.cfx.core.launcher.cfx_container.extract_mount_paths(container_dict: dict) → dict#

Extract host and container mount paths from a container configuration dictionary.

This function looks for a “volumes” key in the input dictionary. If present, it expects the value to be a list of volume specifications. It extracts mount paths for test home mounts and temp directory mounts from the first two volumes (if available).

Returns a dictionary with the following keys:

  • host_mount_path: Path on the host for the first volume (or None).

  • container_mount_path: Path in the container for the first volume (or None).

  • host_temporary_directory_path: Path on the host for the second volume (or None).

  • container_temporary_directory_path: Path in the container for the second volume (or None).

Parameters:
container_dictdict

Container configuration dictionary.

Returns:
dict

Dictionary containing extracted mount paths.

ansys.cfx.core.launcher.cfx_container.replace_container_path_with_host_path(line: str, mount_paths: dict[str, str]) → str#

Replace the first occurrence of a container path in the given line with its corresponding host path.

Parameters:
linestr

Input string potentially containing a container path.

mount_pathsdict[str, str]

Dictionary with keys:

  • container_mount_path

  • host_mount_path

  • container_temporary_directory_path

  • host_temporary_directory_path

Returns:
str

Line with the container path replaced by the host path, if found.

ansys.cfx.core.launcher.cfx_container.replace_host_path_with_container_path(line: str, mount_paths: dict[str, str]) → str#

Replace the first occurrence of a host path in the given line with its corresponding container path.

Parameters:
linestr

Input string potentially containing a host path.

mount_pathsdict[str, str])

Dictionary with keys:

  • container_mount_path

  • host_mount_path

  • container_temporary_directory_path

  • host_temporary_directory_path

Returns:
str

Line with the host path replaced by the container path, if found.

ansys.cfx.core.launcher.cfx_container.start_cfx_container(args: List[str], container_dict: dict | None = None) → tuple[int, str]#

Start a CFX container.

Parameters:
argsList[str]

List of CFX launch arguments.

container_dictdict, default: None

Dictionary with Docker container configuration.

Returns:
tuple

Either:

  • (str, str): For Unix domain socket server address.

  • (str, int, str): For TCP/IP server address.

Raises:
TimeoutError

If the CFX container launch reaches timeout.

Notes

Uses configure_container_dict() to parse the optional container_dict configuration.

This function should usually not be called directly. It is automatically used by the launch_cfx() function.