Server factory, server configuration and communication protocols#

Contains the server factory as well as the communication protocols and server configurations available.

class ansys.dpf.core.server_factory.CommunicationProtocols#

Defines available communication protocols

gRPC = "gRPC"

Client/Server communication via gRPC.

InProcess = "InProcess"

Load the DPF libraries in the Python process, communicates via a CLayer (shared memory).

class ansys.dpf.core.server_factory.DockerConfig(use_docker: bool = False, docker_name: str = '', mounted_volumes: dict | None = None, extra_args: str = '')#

Intermediate class encapsulating all the configuration options needed to run a docker image of DPF and holding tools to communicate with Docker.

Parameters:

  • use_docker (bool, optional) – Whether the DPF server should be started in a Docker Container by default.

  • docker_name (str, optional) – Name of Docker Image to run.

  • mounted_volumes (dict, optional) – Dictionary of key = local path and value = path of mounted volumes in the Docker Image. To prevent from uploading result files on the Docker Image ansys.dpc.core.server_factory.RunningDockerConfig.replace_with_mounted_volumes() iterates through this dictionary to replace local path instances by their mapped value.

  • extra_args (str, optional) – Extra arguments to add to the docker run command.

property use_docker: bool#

Whether the DPF server should be started in a Docker Container by default.

Return type:

bool

property docker_name: str#

Name of Docker Image to run.

Return type:

str

property mounted_volumes: dict#

Dictionary of key = local path and value = path of mounted volumes in the Docker Image. To prevent from uploading result files on the Docker Image ansys.dpc.core.server_factory.RunningDockerConfig.replace_with_mounted_volumes() iterates through this dictionary to replace local path instances by their mapped value.

Return type:

dict

property extra_args: str#

Extra arguments to add to the docker run command.

Return type:

str

docker_run_cmd_command(docker_server_port: int, local_port: int)#

Creates the docker run command with the DockerConfig attributes as well as the docker_server_port and local_port passed in as parameters.

Parameters:

  • docker_server_port (int) – Port used inside the Docker Container to run the gRPC server.

  • local_port (int) – Port exposed outside the Docker container bounded to the internal docker_server_port.

Return type:

str

static find_port_available_for_docker_bind(port: int)#

Checks for available internal docker_server_port by looking at the stdout of all running Docker Containers.

Parameters:

port (int) –

Returns:

port

Return type:

int

class ansys.dpf.core.server_factory.ServerConfig(protocol: str = 'InProcess', legacy: bool = False)#

Provides an instance of ServerConfig object to manage the server type used. The default parameters can be overwritten using the DPF_SERVER_TYPE environment variable. DPF_SERVER_TYPE=INPROCESS, DPF_SERVER_TYPE=GRPC, DPF_SERVER_TYPE=LEGACYGRPC can be used.

Parameters:

  • protocol (CommunicationProtocols, optional) – Communication protocol for DPF server (e.g. InProcess, gRPC)

  • legacy (bool, optional) – If legacy is set to True, the server will be using ansys-grpc-dpf Python module. If not, it will communicate with DPF binaries using ctypes and DPF CLayer calls.

Examples

Use constructor parameters to manually create servers.

>>> from ansys.dpf import core as dpf
>>> in_process_config = dpf.ServerConfig(
...     protocol=dpf.server_factory.CommunicationProtocols.InProcess, legacy=False)
>>> grpc_config = dpf.ServerConfig(
...     protocol=dpf.server_factory.CommunicationProtocols.gRPC, legacy=False)
>>> legacy_grpc_config = dpf.ServerConfig(
...     protocol=dpf.server_factory.CommunicationProtocols.gRPC, legacy=True)
>>> in_process_server = dpf.start_local_server(config=in_process_config, as_global=False)  
>>> grpc_server = dpf.start_local_server(config=grpc_config, as_global=False)  
>>> legacy_grpc_server = dpf.start_local_server(config=legacy_grpc_config, as_global=False)

Use the environment variable to set the default server configuration.

>>> import os
>>> os.environ["DPF_SERVER_TYPE"] = "INPROCESS"
>>> dpf.start_local_server()  
<ansys.dpf.core.server_types.InProcessServer object at ...>
ansys.dpf.core.server_factory.get_default_server_config(server_lower_than_or_equal_to_0_3: bool = False, docker_config: ansys.dpf.core.server_factory.DockerConfig | None = None)#

Returns the default configuration depending on the server version.

  • if ansys.dpf.core.SERVER_CONFIGURATION is not None, then this variable is taken

  • if server_lower_than_or_equal_to_0_3 is True, then LegacyGrpcServer is taken

  • if DPF_SERVER_TYPE environment variable is set to INPROCESS, GRPC, or LEGACYGRPC, then this variable is taken

  • else DEFAULT_COMMUNICATION_PROTOCOL and DEFAULT_LEGACY are used.

Raises:

If DPF_SERVER_TYPE environment variable is set to unknown value. –

ansys.dpf.core.server_factory.get_default_remote_server_config()#

Returns the default configuration for gRPC communication. Follows get_default_server_config

Raises:

If DPF_SERVER_TYPE environment variable is set to unknown value. –

class ansys.dpf.core.server_factory.AvailableServerConfigs#

Defines available server configurations

LegacyGrpcServer = ServerConfig(CommunicationProtocols.gRPC, legacy=True)

Using gRPC communication through the python module ansys.grpc.dpf.

InProcess = ServerConfig(CommunicationProtocols.InProcess, legacy=False)

Loading DPF in Process.

GrpcServer = ServerConfig(CommunicationProtocols.gRPC, legacy=False)

Using gRPC communication through DPF gRPC CLayer Ans.Dpf.GrpcClient.

Examples

>>> from ansys.dpf import core as dpf
>>> in_process_config = dpf.AvailableServerConfigs.InProcessServer
>>> grpc_config = dpf.AvailableServerConfigs.GrpcServer
>>> legacy_grpc_config = dpf.AvailableServerConfigs.LegacyGrpcServer
>>> in_process_server = dpf.start_local_server(config=in_process_config, as_global=False)  
>>> grpc_server = dpf.start_local_server(config=grpc_config, as_global=False)  
>>> legacy_grpc_server = dpf.start_local_server(config=legacy_grpc_config, as_global=False)
class ansys.dpf.core.server_factory.RunningDockerConfig(docker_config: ansys.dpf.core.server_factory.DockerConfig | None = None, server_id: int | None = None, docker_server_port: int | None = None)#

Holds all the configuration options and the process information of a running Docker image of a DPF server.

Parameters:

  • docker_config (DockerConfig, optional) – DockerConfig used to start the docker.

  • server_id (int, optional) – Running Docker Container id.

  • docker_server_port (int, optional) – Local port exposed to the docker image.

property use_docker: bool#

Whether the DPF server should be started in a Docker Container by default.

Return type:

bool

property docker_server_port: int#

Port used inside the Docker Container to run the gRPC server.

Return type:

int

property server_id: int#

Running Docker Container id.

Return type:

int

property docker_name: str#

Name of Docker running Image.

Return type:

str

property mounted_volumes: dict#

Dictionary of local path to docker path of volumes mounted in the Docker Image. These paths are checked for when result files are looked for by the server to prevent from uploading them.

Return type:

dict

property extra_args: str#

Extra arguments used in the docker run command

Return type:

str

replace_with_mounted_volumes(path: str)#

Replace local path found in the list of mounted volumes by their mounted path in the docker.

Parameters:

path (str) – Path to search for occurrences of mounted volumes.

Returns:

path

Return type:

str

remove_docker_image()#

Stops and Removes the Docker image with its id==server_id

Return type:

None

listen_to_process(log: logging.Logger, cmd_lines: list, lines: list, timeout: float, stdout: bool = True)#

Search inside the Docker Container stdout log to fill in this instance’s attributes.

Parameters:

  • log (Logger) – Instance of logging to add debug info to.

  • cmd_lines (list) – Stdout of the shell process run docker run command.

  • lines (list) – Internal Container’s stdout are copied into lines.

  • timeout (float) – When to stop searching for stdout.

  • stdout (bool, optional) – Whether to check stdout or stderr.

Return type:

None

class ansys.dpf.core.server_factory.ServerFactory#

Factory for server type choice depending on current configuration.