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

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

@@ -1,5 +1,5 @@
 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,
@@ -288,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
@@ -316,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`` command. Because the server that PySystemCoupling
-    connects to did not exist prior to 23.1 (2023 R1), if no version query
-    exists, the version is assumed to be 23.1.
-
-    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 "23.1"

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/grpc_client.py

@@ -90,28 +90,38 @@ class SycGrpc(object):
 
         working_dir = kwargs.pop("working_dir", None)
         port = kwargs.pop("port", None)
+        version = kwargs.pop("version", None)
 
         if os.environ.get("SYC_LAUNCH_CONTAINER") == "1":
             mounted_from = working_dir if working_dir else "./"
             mounted_to = "/working"
-            self.start_container_and_connect(mounted_from, mounted_to, port=port)
+            self.start_container_and_connect(
+                mounted_from, mounted_to, port=port, version=version
+            )
         else:  # pragma: no cover
             if port is None:
                 port = _find_port()
             if working_dir is None:
                 working_dir = "."
             LOG.debug("Starting process...")
-            self.__process = SycProcess(_LOCALHOST_IP, port, working_dir, **kwargs)
+            self.__process = SycProcess(
+                _LOCALHOST_IP, port, working_dir, version, **kwargs
+            )
             LOG.debug("...started")
             self._connect(_LOCALHOST_IP, port)
 
     def start_container_and_connect(
-        self, mounted_from: str, mounted_to: str, network: str = None, port: int = None
+        self,
+        mounted_from: str,
+        mounted_to: str,
+        network: str = None,
+        port: int = None,
+        version: str = None,
     ):
         """Start the System Coupling container and establish a connection."""
         LOG.debug("Starting container...")
         port = port if port is not None else _find_port()
-        start_container(mounted_from, mounted_to, network, port)
+        start_container(mounted_from, mounted_to, network, port, version)
         LOG.debug("...started")
         self._connect(_LOCALHOST_IP, port)
 

ansys/systemcoupling/core/client/syc_container.py

@@ -2,12 +2,23 @@ import os
 from pathlib import Path
 import subprocess
 
+from ansys.systemcoupling.core.syc_version import SYC_VERSION_DOT, normalize_version
+
 _MPI_VERSION_VAR = "FLUENT_INTEL_MPI_VERSION"
 _MPI_VERSION = "2021"
 
+_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"
+
 
 def start_container(
-    mounted_from: str, mounted_to: str, network: str, port: int
+    mounted_from: str, mounted_to: str, network: str, port: int, version: str
 ) -> None:
     """Start a System Coupling container.
 
@@ -17,7 +28,11 @@ def start_container(
         gPRC server local port, mapped to the same port in container.
     """
     args = ["-m", "cosimgui", f"--grpcport=0.0.0.0:{port}"]
-    image_tag = os.getenv("SYC_IMAGE_TAG", "v23.1.0")
+
+    if version:
+        image_tag = _image_tag(version)
+    else:
+        image_tag = os.getenv("SYC_IMAGE_TAG", _DEFAULT_IMAGE_TAG)
 
     mounted_from = str(Path(mounted_from).absolute())
 
@@ -36,7 +51,7 @@ def start_container(
         f"{_MPI_VERSION_VAR}={_MPI_VERSION}",
         "-e",
         f"AWP_ROOT=/ansys_inc",
-        f"ghcr.io/pyansys/pysystem-coupling:{image_tag}",
+        f"ghcr.io/ansys/pysystem-coupling:{image_tag}",
     ] + args
 
     if network:

ansys/systemcoupling/core/client/syc_process.py

@@ -5,11 +5,12 @@ import subprocess
 
 import psutil
 
+from ansys.systemcoupling.core.syc_version import SYC_VERSION_CONCAT, normalize_version
 from ansys.systemcoupling.core.util.logging import LOG
 
 _isWindows = any(platform.win32_ver())
 
-_CURR_VER = "231"
+_CURR_VER = SYC_VERSION_CONCAT
 _INSTALL_ROOT_ENV = "AWP_ROOT"
 _INSTALL_ROOT_VER_ENV = _INSTALL_ROOT_ENV + _CURR_VER
 _SC_ROOT_ENV = "SYSC_ROOT"
@@ -22,8 +23,10 @@ _SCRIPT_NAME = "systemcoupling" + _SCRIPT_EXT
 
 
 class SycProcess:  # pragma: no cover
-    def __init__(self, host, port, working_dir, **kwargs):
-        self.__process = _start_system_coupling(host, port, working_dir, **kwargs)
+    def __init__(self, host, port, working_dir, version=None, **kwargs):
+        self.__process = _start_system_coupling(
+            host, port, working_dir, version, **kwargs
+        )
 
     def end(self):
         if self.__process and self.__process.poll() is None:
@@ -41,11 +44,18 @@ class SycProcess:  # pragma: no cover
             self.__process = None
 
 
-def _start_system_coupling(host, port, working_dir, **kwargs):  # pragma: no cover
+def _start_system_coupling(
+    host, port, working_dir, version, **kwargs
+):  # pragma: no cover
     env = deepcopy(os.environ)
     env["PYTHONUNBUFFERED"] = "1"
     env["SYC_GUI_SILENT_SERVER"] = "1"
-    args = [_path_to_system_coupling(), "-m", "cosimgui", f"--grpcport={host}:{port}"]
+    args = [
+        _path_to_system_coupling(version),
+        "-m",
+        "cosimgui",
+        f"--grpcport={host}:{port}",
+    ]
 
     # Extract arguments that we currently recognize - scope to extend in future
     nprocs = kwargs.pop("nprocs", None)
@@ -72,13 +82,29 @@ def _start_system_coupling(host, port, working_dir, **kwargs):  # pragma: no cov
     )
 
 
-def _path_to_system_coupling():  # pragma: no cover
+def _path_to_system_coupling(version):  # pragma: no cover
+    if version is not None:
+        if os.environ.get(_SC_ROOT_ENV, None) or os.environ.get(
+            _INSTALL_ROOT_ENV, None
+        ):
+            raise ValueError(
+                f"An explicit version, {version}, has been specified for "
+                "launching System Coupling, while at least one of the "
+                f"environment variables {_SC_ROOT_ENV} and {_INSTALL_ROOT_ENV} "
+                "is set. To remove the ambiguity, either unset the environment "
+                "variable(s) or do not provide the version argument."
+            )
+
     scroot = os.environ.get(_SC_ROOT_ENV, None)
 
     if not scroot:
         scroot = os.environ.get(_INSTALL_ROOT_ENV, None)
         if scroot is None:
-            scroot = os.environ.get(_INSTALL_ROOT_VER_ENV, None)
+            if version is None:
+                scroot = os.environ.get(_INSTALL_ROOT_VER_ENV, None)
+            else:
+                ver_maj, ver_min = normalize_version(version)
+                scroot = os.environ.get(f"{_INSTALL_ROOT_ENV}{ver_maj}{ver_min}", None)
         if scroot:
             scroot = os.path.join(scroot, "SystemCoupling")
 

ansys/systemcoupling/core/examples/downloads.py

@@ -37,8 +37,8 @@ def _decompress(filename: str) -> None:
 
 
 def _get_file_url(filename: str, directory: Optional[str] = None) -> str:
-    root_url = "https://github.com/pyansys/example-data/raw/master/"
-    # root_url = "https://github.com/pyansys/pysystem-coupling/raw/feature/more_doc/"
+    root_url = "https://github.com/ansys/example-data/raw/master/"
+    # root_url = "https://github.com/ansys/pysystem-coupling/raw/feature/more_doc/"
     if directory:
         return f"{root_url}" f"{directory}/{filename}"
     return f"{root_url}/{filename}"

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
@@ -161,7 +167,7 @@ class Session:
 
         Use of this API is not particularly encouraged, but there may be
         situations where it is useful to access functionality that, for
-        some reason, not been fully exposed in PySystemCoupling.
+        some reason, has not been fully exposed in PySystemCoupling.
 
         Furthermore, existing users of the System Coupling CLI may initially
         find it comfortable to work with the familiar API while transitioning