ansys-systemcoupling-core 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

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

@@ -1,10 +1,9 @@
 from copy import deepcopy
-from typing import Tuple
+from typing import Dict, List, Tuple
 
 from ansys.systemcoupling.core.adaptor.impl.injected_commands import (
     get_injected_cmd_data,
 )
-from ansys.systemcoupling.core.syc_version import SYC_VERSION_DOT
 from ansys.systemcoupling.core.util.name_util import to_python_name
 
 
@@ -289,22 +288,85 @@ def get_extended_cmd_metadata(api) -> list:
         Object providing access to the System Coupling *native API*.
     """
 
+    def find_item_by_name(items: List[Dict], name: str) -> dict:
+        for item in items:
+            if item["name"] == name:
+                return item
+        raise RuntimeError(f"Did not find dict element of list with 'name' == {name}")
+
     def merge_data(target: list, source: list) -> None:
         target_names = set(d["name"] for d in target)
         source_names = set(d["name"] for d in source)
         new_names = source_names - target_names
         common_names = source_names & target_names
 
+        # Injected commands can either be completely new commands injected into
+        # the set of available commands, or can be "overrides" that replace the
+        # SyC command that would have been generated. Occasionally, we still
+        # want to generate the command that is being replaced so that we can
+        # call it internally. This is identified by a "pysyc_internal_name"
+        # field. In this case we split the command data into an injected command
+        # and a "normal" command but with the internal name as the pysyc name
+        # for the latter.
+
+        special_injected_commands = [
+            name
+            for name in common_names
+            if "pysyc_internal_name" in find_item_by_name(source, name)
+        ]
+
+        for name in special_injected_commands:
+            src_item = find_item_by_name(source, name)
+            tgt_item = find_item_by_name(target, name)
+
+            # Target item becomes a "normally" exposed SyC command except that
+            # it is "internal" on the PySyC side - only intended for internal
+            # PySyC use.  It will be given a special internal name rather than
+            # the one derived from its SyC name. It will also have its doc
+            # info removed.
+
+            # - Take a copy of tgt before we remove doc.
+            tgt_copy = deepcopy(tgt_item)
+            if "doc" in tgt_item:
+                tgt_item["doc"] = "For internal use only."
+
+            for arg in tgt_item.get("args", []):
+                _, arg_info = arg
+                if "doc" in arg_info:
+                    arg_info["doc"] = "..."
+
+            # - Name for PySyC exposure is the "pysyc_internal_name" from the source item
+            tgt_item["pyname"] = src_item["pysyc_internal_name"]
+
+            # Source item becomes a normal injected command. It is processed like the
+            # items in the common_names later but has special treatment for its
+            # doc and arguments. That is done here, so it will be removed from
+            # common_names and added to new_names.
+            for k, v in tgt_copy.items():
+                if k in ("essentialArgNames", "optionalArgNames", "args"):
+                    src_item[k] = src_item.get(f"{k}_extra", []) + v
+                elif k == "doc":
+                    prefix = src_item.get(f"{k}_prefix", "")
+                    if prefix:
+                        prefix += "\n\n"
+                    suffix = src_item.get(f"{k}_suffix", "")
+                    if suffix:
+                        suffix = "\n" + suffix
+                    src_item[k] = prefix + v + suffix
+                else:
+                    src_item[k] = v
+
+            src_item["name"] = src_item["pyname"]
+
+            common_names.remove(name)
+            new_names.add(src_item["name"])
+
         for src_item in source:
             name = src_item["name"]
             if name in new_names:
                 target.append(src_item)
             elif name in common_names:
-                tgt_item = None
-                for titem in target:
-                    if titem["name"] == name:
-                        tgt_item = titem
-                        break
+                tgt_item = find_item_by_name(target, name)
 
                 # Single-level merge of source item dictionary into
                 # target item dictionary. If any aspect of the arguments
@@ -317,37 +379,3 @@ def get_extended_cmd_metadata(api) -> list:
     injected_data = get_injected_cmd_data()
     merge_data(cmd_metadata, injected_data)
     return cmd_metadata
-
-
-def get_syc_version(api) -> str:
-    """Get the System Coupling version.
-
-    The version is returned in a string like ``"23.2"``.
-
-    System Coupling versions earlier than 23.2 (2023 R2) do not expose
-    the ``GetVersion`` query. Because the first version of the server
-    that PySystemCoupling is able to connect to is 23.1 (2023 R1), the
-    version is assumed to be 23.1 if no version query exists.
-
-    Parameters
-    ----------
-    api : NativeApi
-        Object providing access to the System Coupling *native API* .
-    """
-
-    def clean_version_string(version_in: str) -> str:
-        year, _, release = version_in.partition(" ")
-        if len(year) == 4 and year.startswith("20") and release.startswith("R"):
-            try:
-                year = int(year[2:])
-                release = int(release[1:])
-                return f"{year}.{release}"
-            except:
-                pass
-        raise RuntimeError(
-            f"Version string {version_in} has invalid format (expect '20yy Rn')."
-        )
-
-    cmds = api.GetCommandAndQueryMetadata()
-    exists = any(cmd["name"] == "GetVersion" for cmd in cmds)
-    return clean_version_string(api.GetVersion()) if exists else SYC_VERSION_DOT

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

@@ -1,7 +1,7 @@
+from ansys.systemcoupling.core.adaptor.impl.get_syc_version import get_syc_version
 from ansys.systemcoupling.core.adaptor.impl.static_info import (
     get_dm_metadata,
     get_extended_cmd_metadata,
-    get_syc_version,
     make_cmdonly_metadata,
     make_combined_metadata,
 )

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

@@ -29,6 +29,7 @@ import sys
 from typing import Dict, Generic, List, NewType, Tuple, TypeVar, Union
 import weakref
 
+from ansys.systemcoupling.core.participant.protocol import ParticipantProtocol
 from ansys.systemcoupling.core.util import name_util
 
 # Type hints
@@ -246,6 +247,17 @@ class SettingsBase(Base, Generic[StateT]):
         out.flush()
 
 
+# TODO: this doesn't make much sense as a "setting" but is needed to
+# make the special form of add_participant work. Ideally we want to move
+# away from treating command arguments as "settings" but that needs to be
+# handled as a separate task.
+class ParticipantSession(SettingsBase[ParticipantProtocol]):
+    """Object conforming to the ``ParticipantProtocol`` runtime protocol
+    for participant session objects."""
+
+    _state_type = ParticipantProtocol
+
+
 class Integer(SettingsBase[int]):
     """Provides an ``Integer`` object that represents an integer value setting."""
 

ansys/systemcoupling/core/client/syc_container.py

@@ -11,6 +11,8 @@ _DEFAULT_IMAGE_TAG = f"v{SYC_VERSION_DOT}.0"
 
 
 def _image_tag(version: str) -> str:
+    if version == "latest":
+        return version
     major, minor = normalize_version(version)
     return f"v{major}.{minor}.0"
 

ansys/systemcoupling/core/participant/manager.py

@@ -0,0 +1,198 @@
+import threading
+from typing import Dict, List, Tuple
+
+from ansys.systemcoupling.core.participant.protocol import ParticipantProtocol
+from ansys.systemcoupling.core.util.logging import LOG
+
+
+class ParticipantManager:
+    """Manages a System Coupling solution in which the participant solvers are
+    provided as "session" objects from other PyAnsys APIs.
+
+    These objects must conform (in a Python "duck typing" sense) to the
+    ``ParticipantProtocol`` protocol.
+
+    The ParticipantManager will play a role whenever participants are added to the
+    analysis using the ``add_participant`` command with ``participant_session`` being the one
+    and only argument.
+
+    In this case, the manager creates ``coupling_participant`` data model objects
+    based on queries to the session object. It will also store the session object
+    for later use if a solve is initiated.
+
+    If ``solve`` is called on the manager, it will coordinate both the connection of the
+    participants to System Coupling and, subsequently, the invocation of their solve
+    operations. In standard System Coupling terms, the solves that are initiated from
+    the "PyAnsys" environment will be regarded by the System Coupling solver as
+    "externally managed".
+
+    .. warning:
+        This facility should be regarded as sub-Beta level.
+        It is likely to be subject to further development, and has fairly limited utility
+        until more participant types support the protocol.
+    """
+
+    def __init__(self, syc_session):
+        self.__participants: Dict[str, ParticipantProtocol] = {}
+        self.__syc_session = syc_session
+        self.__connection_lock = threading.Lock()
+        self.clear()
+
+    def clear(self):
+        self.__participants: Dict[str, ParticipantProtocol] = {}
+        self.__n_connected = 0
+        self.__solve_exception = None
+
+    def add_participant(self, participant_session: ParticipantProtocol) -> str:
+        participant_name = (
+            f"{participant_session.participant_type}-{len(self.__participants) + 1}"
+        )
+
+        setup = self.__syc_session.setup
+
+        part_state = setup.coupling_participant.create(participant_name)
+        part_state.participant_type = participant_session.participant_type
+        part_state.participant_analysis_type = participant_session.get_analysis_type()
+        part_state.execution_control.option = "ExternallyManaged"
+
+        setup.analysis_control.analysis_type = (
+            participant_session.get_analysis_type()
+        )  # TODO: this logic isn't quite right, maybe delegate to controller
+
+        for variable in participant_session.get_variables():
+            part_state.variable.create(variable.name).set_state(
+                {
+                    "tensor_type": variable.tensor_type,
+                    "is_extensive": variable.is_extensive,
+                    "location": variable.location,
+                    "quantity_type": variable.quantity_type,
+                    "participant_display_name": variable.display_name,
+                    "display_name": variable.display_name.replace(
+                        " ", "_"
+                    ),  # TODO: delegate this to controller
+                }
+            )
+
+        for region in participant_session.get_regions():
+            part_state.region.create(region.name).set_state(
+                {
+                    "topology": region.topology,
+                    "input_variables": region.input_variables,
+                    "output_variables": region.output_variables,
+                    "display_name": region.display_name,
+                }
+            )
+
+        self.__participants[participant_name] = participant_session
+        return participant_name
+
+    def solve(self):
+        self.__solve_exception = None
+        self._clear_n_connected()
+
+        if len(self.__participants) == 0:
+            # Fall back to normal solve
+            self.__syc_session.solution._solve()
+            return
+
+        # TODO : if we *don't* check for validation error before solve, and
+        # leave it for the SyC Solve() to find them, we see participants hang
+        # during connection. (This is independent of PySyC.)
+
+        if any(
+            msg
+            for msg in self.__syc_session.setup.get_status_messages()
+            if msg["level"] == "Error"
+        ):
+            raise RuntimeError(
+                "The setup data contains errors. solve() cannot proceed until these are fixed."
+            )
+
+        syc_solve_thread = threading.Thread(target=self._syc_solve)
+        try:
+            self._do_solve(syc_solve_thread)
+        finally:
+            syc_solve_thread.join()
+            LOG.info("SyC solve joined.")
+
+        if self.__solve_exception:
+            raise self.__solve_exception
+
+    def _do_solve(self, syc_solve_thread):
+        connection_threads = [
+            threading.Thread(
+                target=lambda host_port, name=name, part=participant: self._participant_connect(
+                    name, host_port, part
+                ),
+                args=(self._get_host_and_port(name), name, participant),
+            )
+            for name, participant in self.__participants.items()
+        ]
+
+        LOG.info("Starting SyC solve thread...")
+        syc_solve_thread.start()
+        LOG.info("Waiting for participants to connect.")
+        _start_threads(connection_threads)
+        _join_threads(connection_threads)
+        connection_threads.clear()
+        if self._get_n_connected() < len(self.__participants):
+            LOG.error("Some participants were unable to connect to System Coupling.")
+            self.__syc_session.solution.abort()
+        else:
+            LOG.info("Participants connected.")
+
+            LOG.info("Starting participant solve threads.")
+            partsolve_threads = [
+                threading.Thread(target=participant.solve)
+                for participant in self.__participants.values()
+            ]
+            _start_threads(partsolve_threads)
+
+            LOG.info("Waiting for all solve threads to join.")
+            _join_threads(partsolve_threads)
+            LOG.info("All participant solve threads joined.")
+
+    def _clear_n_connected(self) -> None:
+        with self.__connection_lock:
+            self.__n_connected = 0
+
+    def _get_n_connected(self) -> int:
+        with self.__connection_lock:
+            return self.__n_connected
+
+    def _increment_n_connected(self) -> None:
+        with self.__connection_lock:
+            self.__n_connected += 1
+
+    def _get_host_and_port(self, participant_name: str) -> Tuple[str, int]:
+        port, host = self.__syc_session._native_api.GetServerInfo()
+        return host, port
+
+    def _participant_connect(
+        self, name: str, host_port: Tuple[str, int], participant: ParticipantProtocol
+    ) -> None:
+        try:
+            participant.connect(*host_port, name)
+            self._increment_n_connected()
+        except Exception as e:
+            LOG.error(f"Participant {name} failed to connect. Exception: {e}")
+
+    def _syc_solve(self):
+        try:
+            # We use `syc_session.solution._solve` here as it is
+            # the lower level solve command. `sys_session.solution.solve`
+            # would bring us recursively back into *this* function
+            self.__syc_session.solution._solve()
+        except Exception as e:
+            self.__solve_exception = e
+            LOG.error(f"Solve terminated with exception: {e}.")
+
+
+def _start_threads(threads: List[threading.Thread]) -> None:
+    for thread in threads:
+        thread.start()
+
+
+def _join_threads(threads: List[threading.Thread]) -> None:
+    for thread in threads:
+        thread.join()

ansys/systemcoupling/core/participant/protocol.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass
+from typing import List, Protocol
+
+
+@dataclass
+class Variable(Protocol):
+    name: str
+    display_name: str
+    tensor_type: str
+    is_extensive: bool
+    location: str
+    quantity_type: str
+
+
+@dataclass
+class Region(Protocol):
+    name: str
+    display_name: str
+    topology: str
+    input_variables: List[str]
+    output_variables: List[str]
+
+
+class ParticipantProtocol(Protocol):
+    """Protocol class to which PyAnsys sessions that are added to a PySystemCoupling
+    session must conform."""
+
+    @property
+    def participant_type(self) -> str:
+        """Type of participant."""
+        ...
+
+    def get_variables(self) -> List[Variable]:
+        """List of variables that can be transferred from the participant."""
+        ...
+
+    def get_regions(self) -> List[Region]:
+        """List of regions on which data transfers can occur."""
+        ...
+
+    def get_analysis_type(self) -> str:
+        """The type of the analysis - "Steady" or "Transient"."""
+        ...
+
+    def connect(self, host: str, port: int, name: str) -> None:
+        """Establish connection between the participant solver and System Coupling."""
+        ...
+
+    def solve(self) -> None:
+        """Run the participant's solve operation."""
+        ...

ansys/systemcoupling/core/session.py

@@ -8,6 +8,7 @@ from ansys.systemcoupling.core.adaptor.impl.injected_commands import (
 from ansys.systemcoupling.core.adaptor.impl.root_source import get_root
 from ansys.systemcoupling.core.adaptor.impl.syc_proxy import SycProxy
 from ansys.systemcoupling.core.native_api import NativeApi
+from ansys.systemcoupling.core.participant.manager import ParticipantManager
 
 if os.environ.get("PYSYC_DOC_BUILD_VERSION"):
     # It is useful to import explicit types while building doc as it
@@ -60,6 +61,7 @@ class Session:
         self.__rpc = rpc
         self.__native_api = None
         self.__syc_version = None
+        self.__part_mgr = ParticipantManager(self)
 
     def exit(self) -> None:
         """Close the System Coupling server instance.
@@ -152,7 +154,11 @@ class Session:
             version = sycproxy.get_version()
             self.__syc_version = version.replace(".", "_")
         root = get_root(sycproxy, category=category, version=self.__syc_version)
-        sycproxy.set_injected_commands(get_injected_cmd_map(category, root, self.__rpc))
+        sycproxy.set_injected_commands(
+            get_injected_cmd_map(
+                self.__syc_version, category, root, self.__part_mgr, self.__rpc
+            )
+        )
         return (root, sycproxy)
 
     @property

ansys/systemcoupling/core/syc_version.py

@@ -2,8 +2,8 @@ from typing import Tuple
 
 # Define constants relating to the default/current version of System Coupling
 
-SYC_MAJOR_VERSION = 23
-SYC_MINOR_VERSION = 2
+SYC_MAJOR_VERSION = 24
+SYC_MINOR_VERSION = 1
 
 SYC_VERSION_CONCAT = f"{SYC_MAJOR_VERSION}{SYC_MINOR_VERSION}"
 SYC_VERSION_DOT = f"{SYC_MAJOR_VERSION}.{SYC_MINOR_VERSION}"
@@ -56,3 +56,27 @@ def normalize_version(version: str) -> Tuple[int, int]:
         return process_major_minor(version[0:2], version[2])
     else:
         raise_error()
+
+
+def compare_versions(version_a: str, version_b: str) -> int:
+    """Compares two version strings that are in any form that can be parsed by
+    ``normalize_version``.
+
+    Returns < 0 if ``version_a`` is an earlier version than ``version_b``, 0
+    if they are the same version, and > 0 if ``version_a`` is a later version
+    than ``version_b``.
+
+    Parameters
+    ----------
+    version_a : str
+        The first version string to compare.
+    version_b: str
+        The second version string to compare.
+    """
+    va_maj, va_min = normalize_version(version_a)
+    vb_maj, vb_min = normalize_version(version_b)
+
+    if va_maj == vb_maj:
+        return va_min - vb_min
+    else:
+        return va_maj - vb_maj

{ansys_systemcoupling_core-0.2.0.dist-info → ansys_systemcoupling_core-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ansys-systemcoupling-core
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Python wrapper for Ansys System Coupling.
 Author-email: "ANSYS, Inc." <pyansys.support@ansys.com>
 Maintainer-email: PyAnsys developers <pyansys.maintainers@ansys.com>
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Requires-Dist: ansys-api-systemcoupling==0.1.0
 Requires-Dist: grpcio>=1.30.0
-Requires-Dist: grpcio-status>=1.30.0,<1.56.1
+Requires-Dist: grpcio-status>=1.30.0,<1.58.1
 Requires-Dist: googleapis-common-protos>=1.50.0
 Requires-Dist: protobuf>=3.20.1,<4.0.0
 Requires-Dist: psutil>=5.7.0
@@ -29,24 +29,24 @@ Requires-Dist: importlib-metadata>=4.0
 Requires-Dist: build ; extra == "build"
 Requires-Dist: black==23.7.0 ; extra == "classesgen"
 Requires-Dist: isort==5.12.0 ; extra == "classesgen"
-Requires-Dist: ansys-sphinx-theme==0.9.9 ; extra == "doc"
+Requires-Dist: ansys-sphinx-theme==0.11.2 ; extra == "doc"
 Requires-Dist: jupyter_sphinx==0.4.0 ; extra == "doc"
 Requires-Dist: matplotlib ; extra == "doc"
 Requires-Dist: numpydoc==1.5.0 ; extra == "doc"
 Requires-Dist: pypandoc==1.11 ; extra == "doc"
 Requires-Dist: pytest-sphinx==0.5.0 ; extra == "doc"
-Requires-Dist: Sphinx==7.0.1 ; extra == "doc"
+Requires-Dist: Sphinx==7.2.6 ; extra == "doc"
 Requires-Dist: sphinx-autobuild==2021.3.14 ; extra == "doc"
-Requires-Dist: sphinx-autodoc-typehints==1.23.3 ; extra == "doc"
+Requires-Dist: sphinx-autodoc-typehints==1.24.0 ; extra == "doc"
 Requires-Dist: sphinx-copybutton==0.5.2 ; extra == "doc"
-Requires-Dist: sphinx-gallery==0.13.0 ; extra == "doc"
-Requires-Dist: sphinx-notfound-page==0.8.3 ; extra == "doc"
-Requires-Dist: sphinxcontrib-websupport==1.2.4 ; extra == "doc"
+Requires-Dist: sphinx-gallery==0.14.0 ; extra == "doc"
+Requires-Dist: sphinx-notfound-page==1.0.0 ; extra == "doc"
+Requires-Dist: sphinxcontrib-websupport==1.2.6 ; extra == "doc"
 Requires-Dist: sphinxemoji==0.2.0 ; extra == "doc"
 Requires-Dist: ansys-fluent-core ; extra == "doc"
 Requires-Dist: ansys-dpf-core ; extra == "doc"
 Requires-Dist: codespell==2.2.5 ; extra == "style"
-Requires-Dist: flake8==6.0.0 ; extra == "style"
+Requires-Dist: flake8==6.1.0 ; extra == "style"
 Requires-Dist: pytest ; extra == "tests"
 Requires-Dist: pytest-cov ; extra == "tests"
 Requires-Dist: psutil>=5.7.0 ; extra == "tests"