ansys-systemcoupling-core 0.4.1__py3-none-any.whl → 0.6__py3-none-any.whl

ansys/systemcoupling/core/adaptor/api_24_2/variable_child.py

@@ -0,0 +1,231 @@
+#
+# This is an auto-generated file.  DO NOT EDIT!
+#
+
+from ansys.systemcoupling.core.adaptor.impl.types import *
+
+from .attribute import attribute
+
+
+class variable_child(Container):
+    """
+    Configure a variable for the coupling participant.
+    """
+
+    syc_name = "child_object_type"
+
+    child_names = ["attribute"]
+
+    attribute: attribute = attribute
+    """
+    attribute child of variable_child.
+    """
+    property_names_types = [
+        ("quantity_type", "QuantityType", "str"),
+        ("location", "Location", "str"),
+        ("participant_display_name", "ParticipantDisplayName", "str"),
+        ("display_name", "DisplayName", "str"),
+        ("data_type", "DataType", "str"),
+        ("real_initial_value", "RealInitialValue", "RealType"),
+        ("integer_initial_value", "IntegerInitialValue", "int"),
+        ("logical_initial_value", "LogicalInitialValue", "bool"),
+        ("string_initial_value", "StringInitialValue", "str"),
+        ("enumeration_initial_value", "EnumerationInitialValue", "int"),
+        ("real_min", "RealMin", "RealType"),
+        ("real_max", "RealMax", "RealType"),
+        ("integer_min", "IntegerMin", "int"),
+        ("integer_max", "IntegerMax", "int"),
+        ("enumeration_min", "EnumerationMin", "int"),
+        ("enumeration_max", "EnumerationMax", "int"),
+        ("tensor_type", "TensorType", "str"),
+        ("is_extensive", "IsExtensive", "bool"),
+    ]
+
+    @property
+    def quantity_type(self) -> str:
+        """Quantity type of the variable.
+
+        Allowed values:
+
+        - \"Unspecified\"
+        - \"Force\"
+        - \"Incremental Displacement\"
+        - \"Temperature\"
+        - \"Heat Rate\"
+        - \"Heat Transfer Coefficient\"
+        - \"Convection Reference Temperature\"
+        - \"Mode Shape\"
+        - \"Electrical Conductivity\" """
+        return self.get_property_state("quantity_type")
+
+    @quantity_type.setter
+    def quantity_type(self, value: str):
+        self.set_property_state("quantity_type", value)
+
+    @property
+    def location(self) -> str:
+        """Data location of the variable (\"Node\" or \"Element\")."""
+        return self.get_property_state("location")
+
+    @location.setter
+    def location(self, value: str):
+        self.set_property_state("location", value)
+
+    @property
+    def participant_display_name(self) -> str:
+        """Variable's display name as defined by the participant solver."""
+        return self.get_property_state("participant_display_name")
+
+    @participant_display_name.setter
+    def participant_display_name(self, value: str):
+        self.set_property_state("participant_display_name", value)
+
+    @property
+    def display_name(self) -> str:
+        """Variable's display name as defined in System Coupling."""
+        return self.get_property_state("display_name")
+
+    @display_name.setter
+    def display_name(self, value: str):
+        self.set_property_state("display_name", value)
+
+    @property
+    def data_type(self) -> str:
+        """Variable's data type as reported by the participant.
+
+        Allowed values (non-FMU case):
+
+        - Real
+        - Complex
+
+        Allowed values (FMU):
+
+        - Real
+        - Integer
+        - Logical
+        - String
+        - Enumeration"""
+        return self.get_property_state("data_type")
+
+    @data_type.setter
+    def data_type(self, value: str):
+        self.set_property_state("data_type", value)
+
+    @property
+    def real_initial_value(self) -> RealType:
+        """Real data start value."""
+        return self.get_property_state("real_initial_value")
+
+    @real_initial_value.setter
+    def real_initial_value(self, value: RealType):
+        self.set_property_state("real_initial_value", value)
+
+    @property
+    def integer_initial_value(self) -> int:
+        """Integer data start value."""
+        return self.get_property_state("integer_initial_value")
+
+    @integer_initial_value.setter
+    def integer_initial_value(self, value: int):
+        self.set_property_state("integer_initial_value", value)
+
+    @property
+    def logical_initial_value(self) -> bool:
+        """Logical data start value."""
+        return self.get_property_state("logical_initial_value")
+
+    @logical_initial_value.setter
+    def logical_initial_value(self, value: bool):
+        self.set_property_state("logical_initial_value", value)
+
+    @property
+    def string_initial_value(self) -> str:
+        """String data start value."""
+        return self.get_property_state("string_initial_value")
+
+    @string_initial_value.setter
+    def string_initial_value(self, value: str):
+        self.set_property_state("string_initial_value", value)
+
+    @property
+    def enumeration_initial_value(self) -> int:
+        """Enumeration data start value."""
+        return self.get_property_state("enumeration_initial_value")
+
+    @enumeration_initial_value.setter
+    def enumeration_initial_value(self, value: int):
+        self.set_property_state("enumeration_initial_value", value)
+
+    @property
+    def real_min(self) -> RealType:
+        """Real data minimum value."""
+        return self.get_property_state("real_min")
+
+    @real_min.setter
+    def real_min(self, value: RealType):
+        self.set_property_state("real_min", value)
+
+    @property
+    def real_max(self) -> RealType:
+        """Real data maximum value."""
+        return self.get_property_state("real_max")
+
+    @real_max.setter
+    def real_max(self, value: RealType):
+        self.set_property_state("real_max", value)
+
+    @property
+    def integer_min(self) -> int:
+        """Integer data minimum value."""
+        return self.get_property_state("integer_min")
+
+    @integer_min.setter
+    def integer_min(self, value: int):
+        self.set_property_state("integer_min", value)
+
+    @property
+    def integer_max(self) -> int:
+        """Integer data maximum value."""
+        return self.get_property_state("integer_max")
+
+    @integer_max.setter
+    def integer_max(self, value: int):
+        self.set_property_state("integer_max", value)
+
+    @property
+    def enumeration_min(self) -> int:
+        """Enumeration data minimum value."""
+        return self.get_property_state("enumeration_min")
+
+    @enumeration_min.setter
+    def enumeration_min(self, value: int):
+        self.set_property_state("enumeration_min", value)
+
+    @property
+    def enumeration_max(self) -> int:
+        """Enumeration data maximum value."""
+        return self.get_property_state("enumeration_max")
+
+    @enumeration_max.setter
+    def enumeration_max(self, value: int):
+        self.set_property_state("enumeration_max", value)
+
+    @property
+    def tensor_type(self) -> str:
+        """Indicates the variable tensor type (\"Scalar\" or \"Vector\").
+
+        \"Vector\" is not supported for the FMU case."""
+        return self.get_property_state("tensor_type")
+
+    @tensor_type.setter
+    def tensor_type(self, value: str):
+        self.set_property_state("tensor_type", value)
+
+    @property
+    def is_extensive(self) -> bool:
+        """Indicates whether this is an extensive property."""
+        return self.get_property_state("is_extensive")
+
+    @is_extensive.setter
+    def is_extensive(self, value: bool):
+        self.set_property_state("is_extensive", value)

ansys/systemcoupling/core/adaptor/api_24_2/write_csv_chart_files.py

@@ -0,0 +1,21 @@
+#
+# This is an auto-generated file.  DO NOT EDIT!
+#
+
+from ansys.systemcoupling.core.adaptor.impl.types import *
+
+
+class write_csv_chart_files(Command):
+    """
+    For each coupling interface, exports a CSV file containing chart data
+    (convergence and source/target quantity transfer values) for
+    that interface.
+
+    Each file is named according to the convention ``<interface>.csv``, where
+    ``<interface>`` is the object name of the corresponding coupling interface.
+
+    This command will overwrite any CSV charting files that already exist,
+    including any that were written during the solution.
+    """
+
+    syc_name = "WriteCsvChartFiles"

ansys/systemcoupling/core/adaptor/api_24_2/write_ensight.py

@@ -0,0 +1,46 @@
+#
+# This is an auto-generated file.  DO NOT EDIT!
+#
+
+from ansys.systemcoupling.core.adaptor.impl.types import *
+
+
+class write_ensight(Command):
+    """
+    Write a file with mesh and results which can be loaded into Ensight for
+    post processing.
+
+    Parameters
+    ----------
+    file_name : str
+        Base name for Ensight files. It will generate <base>.encas file which
+        should be loaded into Ensight. Other files are generated for geometry
+        and variables.
+    binary : bool, optional
+        To control if file is to be written in binary format or ASCII. ASCII
+        slows down performance, but may be useful for debugging and seeing
+        raw data.
+
+    """
+
+    syc_name = "WriteEnSight"
+
+    argument_names = ["file_name", "binary"]
+
+    class file_name(String):
+        """
+        Base name for Ensight files. It will generate <base>.encas file which
+        should be loaded into Ensight. Other files are generated for geometry
+        and variables.
+        """
+
+        syc_name = "FileName"
+
+    class binary(Boolean):
+        """
+        To control if file is to be written in binary format or ASCII. ASCII
+        slows down performance, but may be useful for debugging and seeing
+        raw data.
+        """
+
+        syc_name = "Binary"

ansys/systemcoupling/core/adaptor/impl/injected_commands.py

@@ -21,55 +21,108 @@
 # SOFTWARE.
 
 from copy import deepcopy
-from typing import Callable, Dict
-
+import os
+import random
+import time
+from typing import Callable, Dict, Optional, Protocol
+
+import ansys.platform.instancemanagement as pypim
+
+from ansys.systemcoupling.core.charts.plot_functions import create_and_show_plot
+from ansys.systemcoupling.core.charts.plotdefinition_manager import (
+    DataTransferSpec,
+    InterfaceSpec,
+    PlotSpec,
+)
+from ansys.systemcoupling.core.native_api import NativeApi
 from ansys.systemcoupling.core.participant.manager import ParticipantManager
 from ansys.systemcoupling.core.participant.mapdl import MapdlSystemCouplingInterface
-from ansys.systemcoupling.core.syc_version import compare_versions
 from ansys.systemcoupling.core.util.yaml_helper import yaml_load_from_string
 
 from .get_status_messages import get_status_messages
 from .types import Container
 
 
+# We cannot import Session directly, so define a protocol for typing.
+# We mainly use it as a means of accessing the "API roots".
+class SessionProtocol(Protocol):
+    case: Container
+    setup: Container
+    solution: Container
+    _native_api: NativeApi
+
+    def download_file(
+        self, file_name: str, local_file_dir: str = ".", overwrite: bool = False
+    ) -> None: ...
+
+    def upload_file(
+        self,
+        file_name: str,
+        remote_file_name: Optional[str] = None,
+        overwrite: bool = False,
+    ) -> None: ...
+
+
 def get_injected_cmd_map(
-    version: str,
     category: str,
-    root_object: Container,
+    session: SessionProtocol,
     part_mgr: ParticipantManager,
     rpc,
 ) -> Dict[str, Callable]:
-    """Gets a dictionary that maps names to functions that implement the injected command.
-
-    The map returned pertains to the commands in the specified category.
+    """Get a dictionary mapping names to functions that implement injected commands
+    for the specified API category.
+
+    Whereas the set of commands that exists by default on the API represents a relatively
+    mechanical exposure of native System Coupling commands to PySystemCoupling, the
+    "injected commands" that are returned from here are either *additional* commands
+    that have no counterpart in System Coupling or *overrides* to existing commands
+    that provide modified or extended behavior.
     """
     ret = {}
 
     if category == "setup":
+        # ``get_injected_cmd_map`` needs to be called during initialisation, where
+        # the session API roots are not necessarily available yet. We therefore
+        # defer their access via the lambda.
+        get_setup_root_object = lambda: session.setup
         ret = {
             "get_setup_summary": lambda **kwargs: rpc.GetSetupSummary(**kwargs),
             "get_status_messages": lambda **kwargs: get_status_messages(
-                rpc, root_object, **kwargs
+                rpc, get_setup_root_object(), **kwargs
             ),
             "add_participant": lambda **kwargs: _wrap_add_participant(
-                version, root_object, part_mgr, **kwargs
+                session, part_mgr, **kwargs
             ),
         }
 
     if category == "solution":
+        get_solution_root_object = lambda: session.solution
+        get_setup_root_object = lambda: session.setup
         ret = {
-            "solve": lambda **kwargs: _wrap_solve(root_object, part_mgr, **kwargs),
+            "solve": lambda **kwargs: _wrap_solve(
+                get_solution_root_object(), part_mgr, **kwargs
+            ),
             "interrupt": lambda **kwargs: rpc.interrupt(**kwargs),
             "abort": lambda **kwargs: rpc.abort(**kwargs),
+            "show_plot": lambda **kwargs: _show_plot(session, **kwargs),
+        }
+
+    if category == "case":
+        get_case_root_object = lambda: session.case
+        ret = {
+            "clear_state": lambda **kwargs: _wrap_clear_state(
+                get_case_root_object(), part_mgr, **kwargs
+            )
         }
 
     return ret
 
 
 def _wrap_add_participant(
-    server_version: str, root_object: Container, part_mgr: ParticipantManager, **kwargs
+    session: SessionProtocol, part_mgr: ParticipantManager, **kwargs
 ) -> str:
-    if session := kwargs.get("participant_session", None):
+    setup = session.setup
+    if participant_session := kwargs.get("participant_session", None):
         if len(kwargs) != 1:
             raise RuntimeError(
                 "If a 'participant_session' argument is passed to "
@@ -78,39 +131,124 @@ def _wrap_add_participant(
         if part_mgr is None:
             raise RuntimeError("Internal error: participant manager is not available.")
 
-        if compare_versions(server_version, "24.1") < 0:
-            raise RuntimeError(
-                f"System Coupling server version '{server_version}' is too low to"
-                "support this form of 'add_participant'. Minimum version is '24.1'."
-            )
-
         # special handling for mapdl session
-        if "ansys.mapdl.core.mapdl_grpc.MapdlGrpc" in str(type(session)):
+        if "ansys.mapdl.core.mapdl_grpc.MapdlGrpc" in str(type(participant_session)):
             return part_mgr.add_participant(
-                participant_session=MapdlSystemCouplingInterface(session)
+                participant_session=MapdlSystemCouplingInterface(participant_session)
             )
 
-        if not hasattr(session, "system_coupling"):
+        if not hasattr(participant_session, "system_coupling"):
             raise RuntimeError(
                 "The 'participant_session' parameter does not provide a "
                 "'system_coupling' attribute and therefore cannot support this "
                 "form of 'add_participant'."
             )
+        return part_mgr.add_participant(
+            participant_session=participant_session.system_coupling
+        )
+
+    if input_file := kwargs.get("input_file", None):
+        session.upload_file(input_file)
 
-        return part_mgr.add_participant(participant_session=session.system_coupling)
+    return setup._add_participant(**kwargs)
 
-    return root_object._add_participant(**kwargs)
 
+def _wrap_clear_state(case: Container, part_mgr: ParticipantManager, **kwargs) -> None:
+    part_mgr.clear()
+    case._clear_state(**kwargs)
 
-def _wrap_solve(root_object: Container, part_mgr: ParticipantManager) -> None:
+
+def _wrap_solve(solution: Container, part_mgr: ParticipantManager) -> None:
     if part_mgr is None:
-        root_object._solve()
+        solution._solve()
     else:
         part_mgr.solve()
 
 
+def _ensure_file_available(session: SessionProtocol, filepath: str) -> str:
+    """If we are in a "PIM" session, copies the file specified by ``filepath``
+    into the working directory, so that it is available for download.
+
+    A suffix is added to the name of the copy to make the name unique, and
+    the new name is returned.
+    """
+    # Note: it is a general issue with files in a PIM session that they can
+    # only be uploaded to/downloaded from the root working directory. We
+    # might want to consider integrating something like this directly into
+    # the file_transfer module later so that it is more seamless.
+
+    if not pypim.is_configured():
+        return filepath
+
+    # Copy file to a unique name in the working directory
+    file_name = os.path.basename(filepath)
+    root_name, _, ext = file_name.rpartition(".")
+    ext = f".{ext}" if ext else ""
+    new_name = f"{root_name}_{int(time.time())}_{random.randint(1, 10000000)}{ext}"
+
+    session._native_api.ExecPythonString(
+        PythonString=f"import shutil\nshutil.copy('{filepath}', '{new_name}')"
+    )
+
+    session.download_file(new_name, ".")
+    return new_name
+
+
+def _show_plot(session: SessionProtocol, **kwargs):
+    setup = session.setup
+    working_dir = kwargs.pop("working_dir", ".")
+    interface_name = kwargs.pop("interface_name", None)
+    if interface_name is None:
+        interfaces = setup.coupling_interface.get_object_names()
+        if len(interfaces) == 0:
+            return
+        if len(interfaces) > 1:
+            raise RuntimeError(
+                "show_plot() currently only supports a single interface."
+            )
+        interface_name = interfaces[0]
+    interface_object = setup.coupling_interface[interface_name]
+    interface_disp_name = interface_object.display_name
+
+    if (transfer_names := kwargs.pop("transfer_names", None)) is None:
+        transfer_names = interface_object.data_transfer.get_object_names()
+
+    if len(transfer_names) == 0:
+        return None
+
+    transfer_disp_names = [
+        interface_object.data_transfer[trans_name].display_name
+        for trans_name in transfer_names
+    ]
+
+    show_convergence = kwargs.pop("show_convergence", True)
+    show_transfer_values = kwargs.pop("show_transfer_values", True)
+
+    # TODO : better way to do this?
+    is_transient = setup.solution_control.time_step_size is not None
+
+    file_path = _ensure_file_available(
+        session, os.path.join(working_dir, "SyC", f"{interface_name}.csv")
+    )
+
+    spec = PlotSpec()
+    intf_spec = InterfaceSpec(interface_name, interface_disp_name)
+    spec.interfaces.append(intf_spec)
+    for transfer in transfer_disp_names:
+        intf_spec.transfers.append(
+            DataTransferSpec(
+                display_name=transfer,
+                show_convergence=show_convergence,
+                show_transfer_values=show_transfer_values,
+            )
+        )
+    spec.plot_time = is_transient
+
+    return create_and_show_plot(spec, [file_path])
+
+
 def get_injected_cmd_data() -> list:
-    """Gets a list of injected command data in the right form to insert
+    """Get a list of injected command data in the right form to insert
     at a convenient point in the current processing.
 
     Because the data returned data is always a new copy, it can be manipulated at will.
@@ -309,4 +447,67 @@ _cmd_yaml = """
     essentialArgNames: []
     optionalArgNames: []
     args: []
+-   name: ClearState
+    pyname: clear_state
+    isInjected: true
+    pysyc_internal_name: _clear_state
+-   name: show_plot
+    pyname: show_plot
+    exposure: solution
+    isInjected: true
+    isQuery: false
+    retType: <class 'NoneType'>
+    doc: |-
+        Shows plots of transfer values and convergence for data transfers
+        of a coupling interface.
+
+    essentialArgNames:
+    - interface_name
+    optionalArgNames:
+    - transfer_names
+    - working_dir
+    - show_convergence
+    - show_transfer_values
+    defaults:
+    - None
+    - "."
+    - True
+    - True
+    args:
+    - #!!python/tuple
+        - interface_name
+        -   pyname: interface_name
+            Type: <class 'str'>
+            type: String
+            doc:  |-
+                Specification of which interface to plot.
+    - #!!python/tuple
+        - transfer_names
+        -   pyname: transfer_names
+            Type: <class 'list'>
+            type: String List
+            doc:  |-
+                Specification of which data transfers to plot. Defaults
+                to ``None``, which means plot all data transfers.
+    - #!!python/tuple
+        - working_dir
+        -   pyname: working_dir
+            Type: <class 'str'>
+            type: String
+            doc:  |-
+                Working directory (defaults = ".").
+    - #!!python/tuple
+        - show_convergence
+        -   pyname: show_convergence
+            Type: <class 'bool'>
+            type: Logical
+            doc:  |-
+                Whether to show convergence plots (defaults to ``True``).
+    - #!!python/tuple
+        - show_transfer_values
+        -   pyname: show_transfer_values
+            Type: <class 'bool'>
+            type: Logical
+            doc:  |-
+                Whether to show transfer value plots (defaults to ``True``).
 """

ansys/systemcoupling/core/adaptor/impl/static_info.py

@@ -23,6 +23,7 @@
 from copy import deepcopy
 from typing import Dict, List, Tuple
 
+from ansys.systemcoupling.core.adaptor.impl.get_syc_version import get_syc_version
 from ansys.systemcoupling.core.adaptor.impl.injected_commands import (
     get_injected_cmd_data,
 )
@@ -310,6 +311,21 @@ def get_extended_cmd_metadata(api) -> list:
         Object providing access to the System Coupling *native API*.
     """
 
+    def fix_up_doc(cmd_metadata):
+        if get_syc_version(api) != "24.2":
+            return cmd_metadata
+
+        # There is a bug in doc text queried from 24.2 SyC. The "*" need
+        # to be escaped to avoid issues in Sphinx. This can be a surgical
+        # fix because 24.2 is frozen now.
+        for cmd in cmd_metadata:
+            if cmd["pyname"] == "add_participant":
+                add_part_cmd = cmd
+                for arg_name, arg_info in add_part_cmd["args"]:
+                    if arg_name == "InputFile":
+                        arg_info["doc"] = arg_info["doc"].replace("*", r"\*")
+        return cmd_metadata
+
     def find_item_by_name(items: List[Dict], name: str) -> dict:
         for item in items:
             if item["name"] == name:
@@ -400,4 +416,5 @@ def get_extended_cmd_metadata(api) -> list:
     cmd_metadata = get_cmd_metadata(api)
     injected_data = get_injected_cmd_data()
     merge_data(cmd_metadata, injected_data)
+    cmd_metadata = fix_up_doc(cmd_metadata)
     return cmd_metadata

ansys/systemcoupling/core/adaptor/impl/syc_proxy.py

@@ -89,6 +89,9 @@ class SycProxy(SycProxyInterface):
             return adapt_native_named_object_keys(state)
         return state
 
+    def get_property_state(self, path, property):
+        return self.__rpc.GetParameter(ObjectPath=path, Name=property)
+
     def delete(self, path):
         self.__rpc.DeleteObject(ObjectPath=path)
 

ansys/systemcoupling/core/adaptor/impl/syc_proxy_interface.py

@@ -48,6 +48,10 @@ class SycProxyInterface(ABC):  # pragma: no cover
     def get_state(self, path):
         pass
 
+    @abstractmethod
+    def get_property_state(self, path, name):
+        pass
+
     @abstractmethod
     def delete(self, path):
         pass