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

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

@@ -21,52 +21,97 @@
 # 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(
-                root_object, part_mgr, **kwargs
+                get_case_root_object(), part_mgr, **kwargs
             )
         }
 
@@ -74,9 +119,10 @@ def get_injected_cmd_map(
 
 
 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 "
@@ -85,46 +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
+        )
 
-        return part_mgr.add_participant(participant_session=session.system_coupling)
+    if input_file := kwargs.get("input_file", None):
+        session.upload_file(input_file)
 
-    return root_object._add_participant(**kwargs)
+    return setup._add_participant(**kwargs)
 
 
-def _wrap_clear_state(
-    root_object: Container, part_mgr: ParticipantManager, **kwargs
-) -> None:
+def _wrap_clear_state(case: Container, part_mgr: ParticipantManager, **kwargs) -> None:
     part_mgr.clear()
-    root_object._clear_state(**kwargs)
+    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.
@@ -327,4 +451,63 @@ _cmd_yaml = """
     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

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

@@ -241,7 +241,7 @@ class SettingsBase(Base, Generic[StateT]):
 
     def get_property_state(self, prop):
         """Get the state of the ``prop`` property ."""
-        return self.sycproxy.get_state(self.syc_path + "/" + self.to_syc_name(prop))
+        return self.sycproxy.get_property_state(self.syc_path, self.to_syc_name(prop))
 
     @staticmethod
     def _print_state_helper(state, out, indent=0, indent_factor=2):

ansys/systemcoupling/core/charts/chart_datatypes.py

@@ -0,0 +1,169 @@
+# Copyright (C) 2023 - 2024 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.
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+"""Common data types for the storage of metadata and data for chart series.
+
+All series are assumed to belong to an interface and to a data transfer within the interface
+
+Raw data should be processed into this format from whatever source is available (CSV file
+or streamed data, for example) and the actual charts will be built from this.
+"""
+
+
+class SeriesType(Enum):
+    CONVERGENCE = 1
+    SUM = 2
+    WEIGHTED_AVERAGE = 3
+
+
+@dataclass
+class TransferSeriesInfo:
+    """Information about the chart series data associated with a data transfer.
+
+    Attributes
+    ----------
+    data_index : int
+        This is used by the data source processor to associate this information (likely
+        obtained from heading or other metadata) with the correct data series.
+        It indexes into the full list of series associated with a given interface.
+    series_type : SeriesType
+        The type of line series.
+    transfer_display_name : str
+        The display name of the data transfer. This is a primary identifier for data
+        transfers because CSV data sources do not currently include information about
+        the underlying data model names of data transfers.
+    disambiguation_index: int
+        This should be set to 0, unless there is more than one data transfer with the
+        same display name. A contiguous range of indexes starting at 0 should be assigned
+        to the list of data transfers with the same display name.
+    participant_display_name : str, optional
+        The display name of the participant. This is required for transfer value series
+        but not for convergence series.
+    line_suffixes: list[str]
+        This should always be empty for convergence series. For transfer value series,
+        it should contain the suffixes for any component series that exist. That is,
+        suffixes for complex components, "real" or "imag", and suffixes for vector
+        components, "x", "y", "z", or a combination of complex and vector component
+        types. The data indexes for individual components of the transfer are assumed
+        to be contiguous from ``data_index``.
+    """
+
+    data_index: int
+    series_type: SeriesType
+    transfer_display_name: str
+    disambiguation_index: int
+    # Remainder for non-CONVERGENCE series only
+    participant_display_name: Optional[str] = None
+    line_suffixes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class InterfaceInfo:
+    """Information about the chart series data associated with a single interface.
+
+    Attributes
+    ----------
+    name : str
+        The name of the coupling interface data model object.
+    display_name : str, optional
+        The display name of the interface object. This may be unassigned initially.
+    is_transient : bool
+        Whether the data on this interface is associated with a transient analysis.
+    transfer_info : list[TransferSeriesInfo]
+        The list of ``TransferSeriesInfo`` associated with this interface.
+    """
+
+    name: str
+    display_name: str = ""  # TODO: check whether this is actually needed.
+    is_transient: bool = False
+    transfer_info: list[TransferSeriesInfo] = field(default_factory=list)
+
+
+@dataclass
+class SeriesData:
+    """The plot data for a single chart line series and information to allow
+    it to be associated with chart metadata.
+
+    An instance of this type is assumed to be associated externally with a
+    single interface.
+
+    Attributes
+    ----------
+    transfer_index : int
+        Index of the ``TransferSeriesInfo`` metadata for this series within the
+        ``InterfaceInfo`` for the interface this series is associated with.
+    component_index : int, optional
+        The component index if this series is one of a set of complex and/or
+        vector components of the transfer. Otherwise is ``None``.
+    start_index : int, optional
+        The starting iteration of the ``data`` field. This defaults to 0 and
+        only needs to be set to a different value if incremental data, such
+        as might arise during "live" update of plots, has become available.
+    data : list[float]
+        The series data. This is always indexed by iteration. Extract time
+        step-based data by using a time step to iteration mapping.
+    """
+
+    transfer_index: int  # Index into transfer_info of associated InterfaceInfo
+    component_index: Optional[int] = None  # Component index if applicable
+
+    start_index: int = 0  # Use when providing incremental data
+
+    data: list[float] = field(default_factory=list)
+
+
+@dataclass
+class InterfaceSeriesData:
+    """The series data for given interface.
+
+    Attributes
+    ----------
+    info : InterfaceInfo
+        The metadata for the interface.
+    series : list[SeriesData]
+        The data for all series associated with the interface.
+    """
+
+    info: InterfaceInfo
+    series: list[SeriesData] = field(default_factory=list)
+
+
+@dataclass
+class TimestepData:
+    """Mappings from iteration to time step and time.
+
+    Attributes
+    ----------
+    timestep : list[int]
+        Timestep indexes, indexed by iteration. Typically, multiple consecutive
+        iteration indexes map to the same timestep index.
+    time: list[float]
+        Time values, indexed by iteration. Typically, multiple consecutive iteration
+        indexes map to the same time value.
+    """
+
+    timestep: list[int] = field(default_factory=list)  # iter -> step index
+    time: list[float] = field(default_factory=list)  # iter -> time