The ``server.py`` module ======================== .. py:module:: ansys.dpf.core.server Summary ------- .. py:currentmodule:: server .. tab-set:: .. tab-item:: Functions .. list-table:: :header-rows: 0 :widths: auto * - :py:obj:`~shutdown_global_server` - Shut down the global DPF server. * - :py:obj:`~has_local_server` - Check if a local DPF gRPC server has been created. * - :py:obj:`~set_server_configuration` - Set the default type of DPF server to use for the current python session, . * - :py:obj:`~port_in_use` - Check if a port is in use at the given host. * - :py:obj:`~shutdown_all_session_servers` - Shut down all active servers created by this module. * - :py:obj:`~start_local_server` - Start a new local DPF server at a given port and IP address. * - :py:obj:`~connect_to_server` - Connect to an existing DPF server. * - :py:obj:`~get_or_create_server` - Return the given server or if None, creates a new one. * - :py:obj:`~available_servers` - Search all available installed DPF servers on the current machine. Description ----------- Server. Contains the directives necessary to start the DPF server. Module detail ------------- .. py:function:: shutdown_global_server() Shut down the global DPF server. .. py:function:: has_local_server() Check if a local DPF gRPC server has been created. :returns: ``True`` when a local DPF gRPC server has been created. :rtype: bool .. py:function:: set_server_configuration(server_config: ansys.dpf.core.server_factory.ServerConfig) -> None Set the default type of DPF server to use for the current python session, . :param server_config: Manages the type of server connection to use by default. :type server_config: ServerConfig .. py:function:: port_in_use(port, host=LOCALHOST) Check if a port is in use at the given host. The port must actually "bind" the address. Just checking to see if a socket can be created is insufficient because it's possible to run into permission errors like: ``An attempt was made to access a socket in a way forbidden by its access permissions.`` :returns: ``True`` when the port is in use, ``False`` when free. :rtype: bool .. py:function:: shutdown_all_session_servers() Shut down all active servers created by this module. .. py:function:: start_local_server(ip: str = LOCALHOST, port: int = DPF_DEFAULT_PORT, ansys_path: pathlib.Path | str = None, as_global: bool = True, load_operators: bool = True, use_docker_by_default: bool = True, docker_config: ansys.dpf.core.server_factory.DockerConfig = RUNNING_DOCKER, timeout: float = 20.0, config: ansys.dpf.core.server_factory.ServerConfig = None, use_pypim_by_default: bool = True, context: ansys.dpf.core.server_context.ServerContext = None) -> ansys.dpf.core.server_types.AnyServerType Start a new local DPF server at a given port and IP address. This method requires Windows and ANSYS 2021 R1 or later. If ``as_global=True``, which is the default) the server is stored globally, replacing the one stored previously. Otherwise, a user must keep a handle on their server. .. warning:: Starting with DPF 2026 R1 and PyDPF 0.15.0, the default gRPC server uses mTLS authentication. Please refer to :ref:`ref_dpf_server_secure_mode` for more information on how to set up the certificates and configure the server and client accordingly. See the ``config`` parameter for more details. :param ip: IP address of the remote or local instance to connect to. The default is ``"LOCALHOST"``. :param port: Port to connect to the remote instance on. The default is ``"DPF_DEFAULT_PORT"``, which is 50054. :param ansys_path: Root path for the Ansys installation directory. For example, ``"/ansys_inc/v212/"``. The default is the latest Ansys installation. :param as_global: Global variable that stores the IP address and port for the DPF module. All DPF objects created in this Python session will use this IP and port. The default is ``True``. :param load_operators: Whether to automatically load the math operators. The default is ``True``. :param use_docker_by_default: If the environment variable DPF_DOCKER is set to a docker name and use_docker_by_default is True, the server is ran as a docker (default is True). :param docker_config: To start DPF server as a docker, specify the docker configuration options here. :param timeout: Maximum number of seconds for the initialization attempt. The default is ``10``. Once the specified number of seconds passes, the connection fails. :param config: Manages the type of server connection to use. Forced to LegacyGrpc on macOS. Defaults to mTLS authenticated gRPC connection. Define the path to the mTLS authentication certificates here if needed. Define the default server authentication configuration with environment variables: - ANSYS_GRPC_CERTIFICATES: path to the certificates directory - DPF_GRPC_MODE: gRPC authentication mode, options are 'mtls' and 'insecure'. More information available at :ref:`ref_dpf_server_secure_mode`. :param use_pypim_by_default: Whether to use PyPIM functionalities by default when a PyPIM environment is detected. Defaults to True. :param context: Defines the settings that will be used to load DPF's plugins. A DPF xml file can be used to list the plugins and set up variables. Default is `server_context.SERVER_CONTEXT`. :returns: The newly created server. :rtype: server .. py:function:: connect_to_server(ip: str = LOCALHOST, port: int = DPF_DEFAULT_PORT, as_global: bool = True, timeout: float = 10.0, config: ansys.dpf.core.server_factory.ServerConfig = None, context: ansys.dpf.core.server_context.ServerContext = None) Connect to an existing DPF server. This method sets the global default channel that is then used for the duration of the DPF session. .. warning:: Starting with DPF 2026 R1 and PyDPF 0.15.0, the default gRPC server uses mTLS authentication. Please refer to :ref:`ref_dpf_server_secure_mode` for more information on how to set up the certificates and configure the server and client accordingly. See the ``config`` parameter for more details. :param ip: IP address of the remote or local instance to connect to. The default is ``"LOCALHOST"``. :param port: Port to connect to the remote instance on. The default is ``"DPF_DEFAULT_PORT"``, which is 50054. :param as_global: Global variable that stores the IP address and port for the DPF module. All DPF objects created in this Python session will use this IP and port. The default is ``True``. :param timeout: Maximum number of seconds for the initialization attempt. The default is ``10``. Once the specified number of seconds passes, the connection fails. :param config: Manages the type of server connection to use. Forced to LegacyGrpc on macOS. Defaults to mTLS authenticated gRPC connection. Define the path to the mTLS authentication certificates here if needed. Define the default server authentication configuration with environment variables: - ANSYS_GRPC_CERTIFICATES: path to the certificates directory - DPF_GRPC_MODE: gRPC authentication mode, options are 'mtls' and 'insecure'. More information available at :ref:`ref_dpf_server_secure_mode`. :param context: Defines the settings that will be used to load DPF's plugins. A DPF xml file can be used to list the plugins and set up variables. Default is `server_context.SERVER_CONTEXT`. .. rubric:: Examples >>> from ansys.dpf import core as dpf Create a server. >>> #server = dpf.start_local_server(ip = '127.0.0.1') >>> #port = server.port Connect to a remote server at a non-default port. >>> #specified_server = dpf.connect_to_server('127.0.0.1', port, as_global=False) Connect to the localhost at the default port. >>> #unspecified_server = dpf.connect_to_server(as_global=False) .. py:function:: get_or_create_server(server: ansys.dpf.core.server_types.AnyServerType | None) -> Union[ansys.dpf.core.server_types.AnyServerType, None] Return the given server or if None, creates a new one. :param server: :returns: **server** :rtype: returns the newly created server, or the server given. .. py:function:: available_servers() Search all available installed DPF servers on the current machine. This method binds new functions to the server module, which helps to choose the appropriate version. .. rubric:: Examples >>> from ansys.dpf import core as dpf >>> #out = dpf.server.available_servers() After this call, you can do the following: >>> #server = dpf.server.start_2024_2_server() Equivalent to: >>> #server = out["2024.1"]() :returns: **server** -- Map of available DPF servers with key=version, value=function starting server when called. See :py:func:`ansys.dpf.core.server.start_local_server` for function doc. :rtype: dict{str:func}