ansys-fluent-core 0.31.dev1__py3-none-any.whl → 0.32.dev0__py3-none-any.whl

ansys/fluent/core/session_utilities.py

@@ -0,0 +1,429 @@
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Session utilities."""
+
+from typing import Any, Dict
+
+import ansys.fluent.core as pyfluent
+from ansys.fluent.core.launcher.container_launcher import DockerLauncher
+from ansys.fluent.core.launcher.pim_launcher import PIMLauncher
+from ansys.fluent.core.launcher.pyfluent_enums import (
+    Dimension,
+    FluentLinuxGraphicsDriver,
+    FluentMode,
+    FluentWindowsGraphicsDriver,
+    Precision,
+    UIMode,
+)
+from ansys.fluent.core.launcher.standalone_launcher import StandaloneLauncher
+from ansys.fluent.core.utils.fluent_version import FluentVersion
+
+
+class SessionBase:
+    """Base class for Fluent sessions.
+
+    This class is not intended to be used directly. Instead, use
+    the `from_connection`, `from_container`, `from_install`,
+    or `from_pim` functions to create a session.
+    """
+
+    _session_mode = {
+        "Meshing": FluentMode.MESHING,
+        "PureMeshing": FluentMode.PURE_MESHING,
+        "PrePost": FluentMode.PRE_POST,
+        "Solver": FluentMode.SOLVER,
+        "SolverAero": FluentMode.SOLVER_AERO,
+        "SolverIcing": FluentMode.SOLVER_ICING,
+    }
+
+    @classmethod
+    def from_install(
+        cls,
+        ui_mode: UIMode | str | None = None,
+        graphics_driver: (
+            FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str
+        ) = None,
+        product_version: FluentVersion | str | float | int | None = None,
+        dimension: Dimension | int | None = None,
+        precision: Precision | str | None = None,
+        processor_count: int | None = None,
+        journal_file_names: None | str | list[str] = None,
+        start_timeout: int = 60,
+        additional_arguments: str = "",
+        env: Dict[str, Any] = {},  # noqa: B006
+        cleanup_on_exit: bool = True,
+        dry_run: bool = False,
+        start_transcript: bool = True,
+        case_file_name: str | None = None,
+        case_data_file_name: str | None = None,
+        lightweight_mode: bool | None = None,
+        py: bool | None = None,
+        gpu: bool | None = None,
+        cwd: str | None = None,
+        fluent_path: str | None = None,
+        topy: str | list | None = None,
+        start_watchdog: bool | None = None,
+        file_transfer_service: Any | None = None,
+    ):
+        """
+        Launch a Fluent session in standalone mode.
+
+        Parameters
+        ----------
+        ui_mode : UIMode
+            Defines the user interface mode for Fluent. Options correspond to values in the ``UIMode`` enum.
+        graphics_driver : FluentWindowsGraphicsDriver or FluentLinuxGraphicsDriver
+            Specifies the graphics driver for Fluent. Options are from the ``FluentWindowsGraphicsDriver`` enum
+            (for Windows) or the ``FluentLinuxGraphicsDriver`` enum (for Linux).
+        product_version : FluentVersion or str or float or int, optional
+            Indicates the version of Ansys Fluent to launch. For example, to use version 2025 R1, pass
+            ``FluentVersion.v251``, ``"25.1.0"``, ``"25.1"``, ``25.1``, or ``251``. Defaults to ``None``,
+            which uses the newest installed version.
+        dimension : Dimension or int, optional
+            Specifies the geometric dimensionality of the Fluent simulation. Defaults to ``None``,
+            which corresponds to ``Dimension.THREE``. Acceptable values are from the ``Dimension`` enum
+            (``Dimension.TWO`` or ``Dimension.THREE``) or integers ``2`` and ``3``.
+        precision : Precision or str, optional
+            Defines the floating point precision. Defaults to ``None``, which corresponds to
+            ``Precision.DOUBLE``. Acceptable values are from the ``Precision`` enum (``Precision.SINGLE``
+            or ``Precision.DOUBLE``) or strings ``"single"`` and ``"double"``.
+        processor_count : int, optional
+            Specifies the number of processors to use. Defaults to ``None``, which uses 1 processor.
+            In job scheduler environments, this value limits the total number of allocated cores.
+        journal_file_names : str or list of str, optional
+            Path(s) to a Fluent journal file(s) that Fluent will execute. Defaults to ``None``.
+        start_timeout : int, optional
+            Maximum time in seconds allowed for connecting to the Fluent server. Defaults to 60 seconds.
+        additional_arguments : str, optional
+            Additional command-line arguments for Fluent, formatted as they would be on the command line.
+        env : dict[str, str], optional
+            A mapping for modifying environment variables in Fluent. Defaults to ``None``.
+        cleanup_on_exit : bool, optional
+            Determines whether to shut down the connected Fluent session when exiting PyFluent or calling
+            the session's `exit()` method. Defaults to True.
+        dry_run : bool, optional
+            If True, does not launch Fluent but prints configuration information instead. The `call()` method
+            returns a tuple containing the launch string and server info file name. Defaults to False.
+        start_transcript : bool, optional
+            Indicates whether to start streaming the Fluent transcript in the client. Defaults to True;
+            streaming can be controlled via `transcript.start()` and `transcript.stop()` methods on the session object.
+        case_file_name : str, optional
+            Name of the case file to read into the Fluent session. Defaults to None.
+        case_data_file_name : str, optional
+            Name of the case data file. If both case and data files are provided, they are read into the session.
+        lightweight_mode : bool, optional
+            If True, runs in lightweight mode where mesh settings are read into a background solver session,
+            replacing it once complete. This parameter is only applicable when `case_file_name` is provided; defaults to False.
+        py : bool, optional
+            If True, runs Fluent in Python mode. Defaults to None.
+        gpu : bool, optional
+            If True, starts Fluent with GPU Solver enabled.
+        cwd : str, optional
+            Working directory for the Fluent client.
+        fluent_path: str, optional
+            User-specified path for Fluent installation.
+        topy :  bool or str, optional
+            A flag indicating whether to write equivalent Python journals from provided journal files; can also specify
+            a filename for the new Python journal.
+        start_watchdog : bool, optional
+            When `cleanup_on_exit` is True, defaults to True; an independent watchdog process ensures that any local
+            GUI-less Fluent sessions started by PyFluent are properly closed when the current Python process ends.
+        file_transfer_service : Any
+            Service for uploading/downloading files to/from the server.
+
+        Raises
+        ------
+        UnexpectedKeywordArgument
+            If an unexpected keyword argument is provided.
+
+        Notes
+        -----
+        In job scheduler environments (e.g., SLURM, LSF, PBS), resources and compute nodes are allocated,
+        and core counts are queried from these environments before being passed to Fluent.
+        """
+        mode = cls._session_mode[cls.__name__]
+        argvals = locals().copy()
+        argvals.pop("cls", None)  # Remove the class reference from the arguments
+        launcher = StandaloneLauncher(**argvals)
+        return launcher()
+
+    @classmethod
+    def from_container(
+        cls,
+        ui_mode: UIMode | str | None = None,
+        graphics_driver: (
+            FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str | None
+        ) = None,
+        product_version: FluentVersion | str | float | int | None = None,
+        dimension: Dimension | int | None = None,
+        precision: Precision | str | None = None,
+        processor_count: int | None = None,
+        start_timeout: int = 60,
+        additional_arguments: str = "",
+        container_dict: dict | None = None,
+        dry_run: bool = False,
+        cleanup_on_exit: bool = True,
+        start_transcript: bool = True,
+        py: bool | None = None,
+        gpu: bool | None = None,
+        start_watchdog: bool | None = None,
+        file_transfer_service: Any | None = None,
+    ):
+        """
+        Launch a Fluent session in container mode.
+
+        Parameters
+        ----------
+        ui_mode : UIMode
+            Defines the user interface mode for Fluent. Options correspond to values in the ``UIMode`` enum.
+        graphics_driver : FluentWindowsGraphicsDriver or FluentLinuxGraphicsDriver
+            Specifies the graphics driver for Fluent. Options are from the ``FluentWindowsGraphicsDriver`` enum
+            (for Windows) or the ``FluentLinuxGraphicsDriver`` enum (for Linux).
+        product_version :  FluentVersion or str or float or int, optional
+            Indicates the version of Ansys Fluent to launch. For example, to use version 2025 R1, pass
+            any of ``FluentVersion.v251``, ``"25.1.0"``, ``"25.1"``, ``25.1``, or ``251``. Defaults to ``None``,
+            which uses the newest installed version.
+        dimension : Dimension or int, optional
+            Specifies the geometric dimensionality of the Fluent simulation. Defaults to ``None``,
+            which corresponds to ``Dimension.THREE``. Acceptable values include ``Dimension.TWO``,
+            ``Dimension.THREE``, or integers ``2`` and ``3``.
+        precision : Precision or str, optional
+            Defines the floating point precision. Defaults to ``None``, which corresponds to
+            ``Precision.DOUBLE``. Acceptable values include ``Precision.SINGLE``,
+            ``Precision.DOUBLE``, or strings ``"single"`` and ``"double"``.
+        processor_count : int, optional
+            Specifies the number of processors to use. Defaults to ``None``, which uses 1 processor.
+            In job scheduler environments, this value limits the total number of allocated cores.
+        start_timeout : int, optional
+            Maximum allowable time in seconds for connecting to the Fluent server. Defaults to 60 seconds.
+        additional_arguments : str, optional
+            Additional command-line arguments for Fluent, formatted as they would be on the command line.
+        container_dict : dict, optional
+            Configuration dictionary for launching Fluent inside a Docker container. See also
+            :mod:`~ansys.fluent.core.launcher.fluent_container`.
+        dry_run : bool, optional
+            If True, does not launch Fluent but prints configuration information instead. If dry running a
+            container start, this method will return the configured ``container_dict``. Defaults to False.
+        cleanup_on_exit : bool
+            Determines whether to shut down the connected Fluent session upon exit or when calling
+            the session's `exit()` method. Defaults to True.
+        start_transcript : bool
+            Indicates whether to start streaming the Fluent transcript in the client. Defaults to True;
+            streaming can be controlled via `transcript.start()` and `transcript.stop()` methods on the session object.
+        py : bool, optional
+            If True, runs Fluent in Python mode. Defaults to None.
+        gpu : bool, optional
+            If True, starts Fluent with GPU Solver enabled.
+        start_watchdog : bool, optional
+            If True and `cleanup_on_exit` is True, an independent watchdog process is run to ensure that any local
+            GUI-less Fluent sessions started by PyFluent are properly closed when the current Python process ends.
+        file_transfer_service : Any, optional
+            Service for uploading/downloading files to/from the server.
+
+        Returns
+        -------
+        Meshing | PureMeshing | Solver | SolverIcing | dict
+            Session object or configuration dictionary if ``dry_run`` is True.
+
+        Raises
+        ------
+        UnexpectedKeywordArgument
+            If an unexpected keyword argument is provided.
+
+        Notes
+        -----
+        In job scheduler environments (e.g., SLURM, LSF, PBS), resources and compute nodes are allocated,
+        and core counts are queried from these environments before being passed to Fluent.
+        """
+        mode = cls._session_mode[cls.__name__]
+        argvals = locals().copy()
+        argvals.pop("cls", None)
+        launcher = DockerLauncher(**argvals)
+        return launcher()
+
+    @classmethod
+    def from_pim(
+        cls,
+        graphics_driver: (
+            FluentWindowsGraphicsDriver | FluentLinuxGraphicsDriver | str | None
+        ) = None,
+        product_version: FluentVersion | str | float | int | None = None,
+        dimension: Dimension | int | None = None,
+        precision: Precision | str | None = None,
+        processor_count: int | None = None,
+        start_timeout: int = 60,
+        additional_arguments: str = "",
+        cleanup_on_exit: bool = True,
+        start_transcript: bool = True,
+        gpu: bool | None = None,
+        start_watchdog: bool | None = None,
+        file_transfer_service: Any | None = None,
+    ):
+        """
+        Launch a Fluent session in `PIM <https://pypim.docs.pyansys.com/version/stable/>`_ mode.
+
+        Parameters
+        ----------
+        graphics_driver : FluentWindowsGraphicsDriver or FluentLinuxGraphicsDriver
+            Specifies the graphics driver for Fluent. Options are from the ``FluentWindowsGraphicsDriver`` enum
+            (for Windows) or the ``FluentLinuxGraphicsDriver`` enum (for Linux).
+        product_version : FluentVersion or str or float or int, optional
+            Indicates the version of Ansys Fluent to launch. For example, to use version 2025 R1, pass
+            any of ``FluentVersion.v251``, ``"25.1.0"``, ``"25.1"``, ``25.1``, or ``251``. Defaults to ``None``,
+            which uses the newest installed version.
+        dimension : Dimension or int, optional
+            Specifies the geometric dimensionality of the Fluent simulation. Defaults to ``None``,
+            which corresponds to ``Dimension.THREE``. Acceptable values include ``Dimension.TWO``,
+            ``Dimension.THREE``, or integers ``2`` and ``3``.
+        precision : Precision or str, optional
+            Defines the floating point precision. Defaults to ``None``, which corresponds to
+            ``Precision.DOUBLE``. Acceptable values include ``Precision.SINGLE``,
+            ``Precision.DOUBLE``, or strings ``"single"`` and ``"double"``.
+        processor_count : int, optional
+            Specifies the number of processors to use. Defaults to ``None``, which uses 1 processor.
+            In job scheduler environments, this value limits the total number of allocated cores.
+        start_timeout : int, optional
+            Maximum allowable time in seconds for connecting to the Fluent server. Defaults to 60 seconds.
+        additional_arguments : str, optional
+            Additional command-line arguments for Fluent, formatted as they would be on the command line.
+        cleanup_on_exit : bool
+            Determines whether to shut down the connected Fluent session upon exit or when calling
+            the session's `exit()` method. Defaults to True.
+        start_transcript : bool
+            Indicates whether to start streaming the Fluent transcript in the client. Defaults to True;
+            streaming can be controlled via `transcript.start()` and `transcript.stop()` methods on the session object.
+        gpu : bool, optional
+            If True, starts Fluent with GPU Solver enabled.
+        start_watchdog : bool, optional
+            If True and `cleanup_on_exit` is True, an independent watchdog process is run to ensure that any local
+            GUI-less Fluent sessions started by PyFluent are properly closed when the current Python process ends.
+        file_transfer_service : Any, optional
+            Service for uploading/downloading files to/from the server.
+
+        Returns
+        -------
+        Union[Meshing, PureMeshing, Solver, SolverIcing, dict]
+            Session object or configuration dictionary if ``dry_run`` is True.
+
+        Raises
+        ------
+        UnexpectedKeywordArgument
+            If an unexpected keyword argument is provided.
+
+        Notes
+        -----
+        In job scheduler environments (e.g., SLURM, LSF, PBS), resources and compute nodes are allocated,
+        and core counts are queried from these environments before being passed to Fluent.
+        """
+        mode = cls._session_mode[cls.__name__]
+        argvals = locals().copy()
+        argvals.pop("cls", None)
+        launcher = PIMLauncher(**argvals)
+        return launcher()
+
+    @classmethod
+    def from_connection(
+        cls,
+        ip: str | None = None,
+        port: int | None = None,
+        server_info_file_name: str | None = None,
+        password: str | None = None,
+    ):
+        """Connect to an existing Fluent server instance.
+
+        Parameters
+        ----------
+        ip : str, optional
+            IP address for connecting to an existing Fluent instance. The
+            IP address defaults to ``"127.0.0.1"``. You can also use the environment
+            variable ``PYFLUENT_FLUENT_IP=<ip>`` to set this parameter.
+            The explicit value of ``ip`` takes precedence over ``PYFLUENT_FLUENT_IP=<ip>``.
+        port : int, optional
+            Port to listen on for an existing Fluent instance. You can use the
+            environment variable ``PYFLUENT_FLUENT_PORT=<port>`` to set a default
+            value. The explicit value of ``port`` takes precedence over
+            ``PYFLUENT_FLUENT_PORT=<port>``.
+        server_info_file_name: str
+            Path to server-info file written out by Fluent server. The default is
+            ``None``. PyFluent uses the connection information in the file to
+            connect to a running Fluent session.
+        password : str, optional
+            Password to connect to existing Fluent instance.
+
+        Raises
+        ------
+        TypeError
+            If the session type does not match the expected session type.
+        """
+        session = pyfluent.connect_to_fluent(
+            ip=ip,
+            port=port,
+            server_info_file_name=server_info_file_name,
+            password=password,
+        )
+
+        expected = "Solver" if cls.__name__ == "PrePost" else cls.__name__
+        actual = session.__class__.__name__
+
+        if actual != expected:
+            raise TypeError(
+                f"Session type mismatch: expected {expected}, got {actual}."
+            )
+
+        return session
+
+
+class Meshing(SessionBase):
+    """Encapsulates a Fluent server for meshing session connection."""
+
+    pass
+
+
+class PureMeshing(SessionBase):
+    """Encapsulates a Fluent server for pure meshing session connection."""
+
+    pass
+
+
+class PrePost(SessionBase):
+    """Encapsulates a Fluent server for pre-post session connection."""
+
+    pass
+
+
+class Solver(SessionBase):
+    """Encapsulates a Fluent server for solver session connection."""
+
+    pass
+
+
+class SolverAero(SessionBase):
+    """Encapsulates a Fluent server for solver aero session connection."""
+
+    pass
+
+
+class SolverIcing(SessionBase):
+    """Encapsulates a Fluent server for solver icing session connection."""
+
+    pass

ansys/fluent/core/solver/flobject.py

@@ -74,6 +74,9 @@ from ansys.fluent.core.pyfluent_warnings import (
     PyFluentUserWarning,
 )
 from ansys.fluent.core.utils.fluent_version import FluentVersion
+from ansys.fluent.core.variable_strategies import (
+    FluentFieldDataNamingStrategy as naming_strategy,
+)
 
 from . import _docstrings
 from .error_message import allowed_name_error_message, allowed_values_error
@@ -196,6 +199,9 @@ def to_python_name(fluent_name: str) -> str:
     return name
 
 
+_to_field_name_str = naming_strategy().to_string if naming_strategy else lambda s: s
+
+
 def _get_python_path_comps(obj):
     """Get python path components for traversing class hierarchy."""
     comps = []
@@ -628,6 +634,18 @@ class RealNumerical(Numerical):
 class Textual(Property):
     """Exposes attribute accessor on settings object - specific to string objects."""
 
+    def set_state(self, state: StateT | None = None, **kwargs):
+        """Set the state of the object.
+
+        Parameters
+        ----------
+        state
+            Either str or VariableDescriptor.
+        kwargs : Any
+            Keyword arguments.
+        """
+        return self.base_set_state(state=_to_field_name_str(state), **kwargs)
+
 
 class DeprecatedSettingWarning(PyFluentDeprecationWarning):
     """Provides deprecated settings warning."""
@@ -853,6 +871,9 @@ class String(SettingsBase[str], Textual):
 
     _state_type = str
 
+    base_set_state = SettingsBase[str].set_state
+    set_state = Textual.set_state
+
 
 class Filename(SettingsBase[str], Textual):
     """A ``Filename`` object representing a file name."""
@@ -1164,6 +1185,10 @@ class Group(SettingsBase[DictStateType]):
             raise
 
     def __setattr__(self, name: str, value):
+        # 'settings_source' will be set to settings object when they are created from builtin settings classes.
+        # We don't allow overwriting it.
+        if name == "settings_source":
+            raise AttributeError("Cannot overwrite settings_source after it is set.")
         attr = None
         try:
             attr = getattr(self, name)
@@ -2103,6 +2128,9 @@ def get_cls(name, info, parent=None, version=None, parent_taboo=None):
         dct["_child_classes"] = {}
         cls = type(pname, bases, dct)
 
+        deprecated_version = info.get("deprecated_version", "")
+        cls._deprecated_version = deprecated_version
+
         taboo = set(dir(cls))
         taboo |= set(
             [

ansys/fluent/core/utils/deprecate.py

@@ -23,14 +23,60 @@
 """Module that provides a method to handle deprecated arguments."""
 
 import functools
+from functools import wraps
 import logging
 import warnings
 
+from deprecated.sphinx import deprecated
+
 from ansys.fluent.core.pyfluent_warnings import PyFluentDeprecationWarning
 
 logger = logging.getLogger("pyfluent.general")
 
 
+def all_deprecators(
+    deprecate_arg_mappings,
+    data_type_converter,
+    deprecated_version,
+    deprecated_reason,
+    warn_message,
+):
+    """Decorator that applies multiple deprecators to a function."""
+
+    def decorator(func):
+        decorated = func
+        for mapping in deprecate_arg_mappings:
+            decorated = deprecate_argument(
+                old_arg=mapping["old_arg"],
+                new_arg=mapping["new_arg"],
+                converter=mapping.get("converter", lambda x: x),
+                warning_cls=PyFluentDeprecationWarning,
+            )(decorated)
+        if data_type_converter:
+            decorated = deprecate_arguments(
+                converter=data_type_converter,
+                warning_cls=PyFluentDeprecationWarning,
+            )(decorated)
+        decorated = deprecated(
+            version=deprecated_version,
+            reason=deprecated_reason,
+        )(decorated)
+
+        @wraps(decorated)
+        def wrapper(*args, **kwargs):
+            if warn_message:
+                warnings.warn(
+                    warn_message,
+                    PyFluentDeprecationWarning,
+                    stacklevel=2,
+                )
+            return decorated(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
 def deprecate_argument(
     old_arg,
     new_arg,

ansys/fluent/core/utils/file_transfer_service.py

@@ -31,7 +31,7 @@ import warnings
 
 from ansys.fluent.core.pyfluent_warnings import PyFluentUserWarning
 from ansys.fluent.core.utils import get_user_data_dir
-from ansys.fluent.core.utils.deprecate import deprecate_argument
+from ansys.fluent.core.utils.deprecate import all_deprecators
 import ansys.platform.instancemanagement as pypim
 
 # Host path which is mounted to the file-transfer-service container
@@ -229,8 +229,24 @@ class ContainerFileTransferStrategy(FileTransferStrategy):
     >>> solver_session.download(file_name="write_elbow.cas.h5", local_directory="<local_directory_path>")
     """
 
-    @deprecate_argument("container_mount_path", "mount_target")
-    @deprecate_argument("host_mount_path", "mount_source")
+    @all_deprecators(
+        deprecate_arg_mappings=[
+            {
+                "old_arg": "container_mount_path",
+                "new_arg": "mount_target",
+                "converter": lambda old_arg_val: old_arg_val,
+            },
+            {
+                "old_arg": "host_mount_path",
+                "new_arg": "mount_source",
+                "converter": lambda old_arg_val: old_arg_val,
+            },
+        ],
+        data_type_converter=None,
+        deprecated_version="v0.23.dev1",
+        deprecated_reason="'container_mount_path' and 'host_mount_path' are deprecated. Use 'mount_target' and 'mount_source' instead.",
+        warn_message="",
+    )
     def __init__(
         self,
         image_name: str | None = None,