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=LOCALHOST, port=DPF_DEFAULT_PORT, ansys_path=None, as_global=True, load_operators=True, use_docker_by_default=True, docker_config=RUNNING_DOCKER, timeout=20.0, config=None, use_pypim_by_default=True, context=None) 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. :param ip: IP address of the remote or local instance to connect to. The default is ``"LOCALHOST"``. :type ip: str, optional :param port: Port to connect to the remote instance on. The default is ``"DPF_DEFAULT_PORT"``, which is 50054. :type port: int, optional :param ansys_path: Root path for the Ansys installation directory. For example, ``"/ansys_inc/v212/"``. The default is the latest Ansys installation. :type ansys_path: str or os.PathLike, optional :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``. :type as_global: bool, optional :param load_operators: Whether to automatically load the math operators. The default is ``True``. :type load_operators: bool, optional :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). :type use_docker_by_default: bool, optional :param docker_config: To start DPF server as a docker, specify the docker configuration options here. :type docker_config: server_factory.DockerConfig, optional :param timeout: Maximum number of seconds for the initialization attempt. The default is ``10``. Once the specified number of seconds passes, the connection fails. :type timeout: float, optional :param config: Manages the type of server connection to use. :type config: ServerConfig, optional :param use_pypim_by_default: Whether to use PyPIM functionalities by default when a PyPIM environment is detected. Defaults to True. :type use_pypim_by_default: bool, optional :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`. :type context: ServerContext, optional :returns: **server** :rtype: server.ServerBase .. py:function:: connect_to_server(ip=LOCALHOST, port=DPF_DEFAULT_PORT, as_global=True, timeout=5, config=None, context=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. :param ip: IP address of the remote or local instance to connect to. The default is ``"LOCALHOST"``. :type ip: str :param port: Port to connect to the remote instance on. The default is ``"DPF_DEFAULT_PORT"``, which is 50054. :type port: int :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``. :type as_global: bool, optional :param timeout: Maximum number of seconds for the initialization attempt. The default is ``10``. Once the specified number of seconds passes, the connection fails. :type timeout: float, optional :param config: Manages the type of server connection to use. Forced to LegacyGrpc on macOS. :type config: ServerConfig, optional :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`. :type context: ServerContext, optional .. 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.BaseServer) -> Union[ansys.dpf.core.server_types.BaseServer, None] Return the given server or if None, creates a new one. :param server: :type server: BaseServer, None :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}