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

ansys/systemcoupling/core/charts/plotdefinition_manager.py

@@ -0,0 +1,303 @@
+# 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 typing import Optional
+
+from ansys.systemcoupling.core.charts.chart_datatypes import InterfaceInfo, SeriesType
+
+
+@dataclass
+class DataTransferSpec:
+    # It's not ideal, but we have to work in terms of display names for transfers,
+    # as that is all we have in the data (the CSV data, at least).
+    display_name: str
+    show_convergence: bool = True
+    show_transfer_values: bool = True
+
+
+@dataclass
+class InterfaceSpec:
+    name: str
+    display_name: str
+    transfers: list[DataTransferSpec] = field(default_factory=list)
+
+
+@dataclass
+class PlotSpec:
+    interfaces: list[InterfaceSpec] = field(default_factory=list)
+    plot_time: bool = False
+
+
+"""
+Convergence subplot:
+    title - Data Transfer Convergence for <interface disp name>
+    x-axis label - Iteration/Time
+    y-axis label - RMS Change in Target Value
+
+    # x-data: []
+    y-data: [([], <label=transfer disp name>)]
+
+    # y-data - we actually want an index
+
+
+Transfer values subplot:
+    title - <interface display name> - <transfer display name> (<value type>)
+    x-axis label: Iteration/time
+    y-axis label: <NOT SET>
+
+    y-data: [([], <label=source|tgt disp name + suffix)]
+
+"""
+
+
+@dataclass
+class SubplotDefinition:
+    """Various data - mainly title and label strings - used in the rendering of
+    a subplot.
+
+    Attributes
+    ----------
+    title: str
+        The title of the subplot.
+    is_log_y: bool
+        Whether the y-axis is logarithmic.
+    x_axis_label: str
+        The label shown on the x-axis.
+    y_axis_label: str
+        The label shown on the y-axis. This is an empty string for convergence plots.
+    index: int = -1
+        The index of this subplot within the list of subplots in the current figure.
+        (In `matplotlib` terms it also indexes the corresponding ``Axes`` item in
+        the figure.)
+    series_labels: list[str] = field(default_factory=list)
+        Labels for each series of the subplot.
+    """
+
+    title: str
+    is_log_y: bool
+    x_axis_label: str
+    y_axis_label: str
+    index: int = -1
+    series_labels: list[str] = field(default_factory=list)
+
+
+class PlotDefinitionManager:
+    def __init__(self, spec: PlotSpec):
+        self._plot_spec = spec
+        self._data_index_map: dict[str, dict[int, tuple[SubplotDefinition, int]]] = {}
+        self._conv_subplots: dict[str, SubplotDefinition] = {}
+        self._transfer_subplots: dict[tuple[str, str, int], SubplotDefinition] = {}
+        self._subplots: list[SubplotDefinition] = []
+        self._allocate_subplots()
+
+    @property
+    def subplots(self) -> list[SubplotDefinition]:
+        return self._subplots
+
+    def subplot_for_data_index(
+        self, interface_name: str, data_index: int
+    ) -> tuple[Optional[SubplotDefinition], int]:
+        """Return the subplot definition, and the line index within the
+        subplot, corresponding to a given ``data_index``.
+
+        The ``data_index`` is a "global" line index for the interface.
+
+        If there is no subplot corresponding to the provided index,
+        return a tuple ``(None, -1)``
+        """
+        try:
+            return self._data_index_map[interface_name][data_index]
+        except KeyError:
+            return (None, -1)
+
+    def get_layout(self) -> tuple[int, int]:
+        nsubplot = len(self._subplots)
+
+        if nsubplot == 1:
+            ncol = 1
+        elif nsubplot < 6:
+            ncol = 2
+        elif nsubplot < 12:
+            ncol = 3
+        elif nsubplot < 18:
+            ncol = 4
+        elif nsubplot < 26:
+            ncol = 5
+        else:
+            raise ValueError(f"Too many subplots requested: {nsubplot}")
+        nrow = nsubplot // ncol
+        if nsubplot % ncol != 0:
+            nrow += 1
+
+        return (nrow, ncol)
+
+    def _allocate_subplots(self):
+        is_time = self._plot_spec.plot_time
+        conv_subplots = {}
+        transfer_subplots = {}
+        subplots = []
+        for interface in self._plot_spec.interfaces:
+            conv = SubplotDefinition(
+                title=f"Data transfer convergence on {interface.display_name}",
+                is_log_y=True,
+                x_axis_label="Time" if is_time else "Iteration",
+                y_axis_label="RMS Change in target value",
+            )
+            # Add this now so that it is before transfer values plots but we may end
+            # up removing it if none of the transfers add a convergence line to it
+            conv_index = len(subplots)
+            subplots.append(conv)
+            keep_conv = False
+            transfer_disambig: dict[str, int] = {}
+            for transfer in interface.transfers:
+                if transfer.display_name in transfer_disambig:
+                    transfer_disambig[transfer.display_name] += 1
+                else:
+                    transfer_disambig[transfer.display_name] = 0
+                if transfer.show_convergence:
+                    keep_conv = True
+                if transfer.show_transfer_values:
+                    transfer_value = SubplotDefinition(
+                        # NB: <VALUETYPE> is a placeholder - substitute later from metadata info
+                        title=f"{interface.display_name} - {transfer.display_name} (<VALUETYPE>)",
+                        is_log_y=False,
+                        x_axis_label="Time" if is_time else "Iteration",
+                        y_axis_label="",
+                    )
+                    transfer_subplots[
+                        (
+                            interface.name,
+                            transfer.display_name,
+                            transfer_disambig[transfer.display_name],
+                        )
+                    ] = transfer_value
+                    subplots.append(transfer_value)
+            if keep_conv:
+                conv_subplots[interface.name] = conv
+            else:
+                subplots[conv_index] = None
+        # Clean out inactive convergence plots
+        self._subplots = [subplot for subplot in subplots if subplot is not None]
+        for i, subplot in enumerate(self._subplots):
+            subplot.index = i
+        self._conv_subplots: dict[str, SubplotDefinition] = conv_subplots
+        self._transfer_subplots: dict[tuple[str, str, int], SubplotDefinition] = (
+            transfer_subplots
+        )
+
+    def set_metadata(self, metadata: InterfaceInfo):
+        """Reconcile the metadata for a single interface with the pre-allocated
+        sub-plots and set up any necessary data routing.
+
+        Typically, this data only starts to be provided once the raw plot data starts
+        being generated.
+        """
+
+        # If a subset of transfers was specified in the plot spec, this is already
+        # implicitly accounted for in self._tranfer_subplots, which will contain only
+        # the active ones. However, some additional work has to be done to filter the
+        # transfers shown on the convergence subplot and we have to go back to the plot
+        # spec to get a list of active transfers.
+        active_transfers = []
+        for intf in self._plot_spec.interfaces:
+            if intf.name == metadata.name:
+                active_transfers = [trans.display_name for trans in intf.transfers]
+                break
+        if not active_transfers:
+            # TODO: should this be an exception?
+            return
+
+        # map from source data index to corresponding (subplot, line index within subplot)
+        data_index_map: dict[int, tuple[SubplotDefinition, int]] = {}
+        interface_name = metadata.name
+        iconv = 0
+
+        # Keep a running count of the transfer value lines associated with a given
+        # transfer. There will be multiple if the transfer variable has vector
+        # and or real/imag components. Note that a transfer is uniquely identified by a
+        # pair (transfer_name, int) because transfer names are not guaranteed to be unique.
+        # The integer is the "disambiguation_index" the transfer's TransferSeriesInfo.
+        transfer_value_line_count: dict[tuple[str, int], int] = {}
+
+        for transfer in metadata.transfer_info:
+            transfer_key = (
+                transfer.transfer_display_name,
+                transfer.disambiguation_index,
+            )
+            if transfer.series_type == SeriesType.CONVERGENCE:
+                if transfer.transfer_display_name not in active_transfers:
+                    # We don't want this transfer on the convergence plot
+                    continue
+                # Clear the entry in case transfer names are not unique. (If another transfer
+                # with the same name needs plotting, then it should appear as a second entry
+                # in active_transfers.)
+                active_transfers[
+                    active_transfers.index(transfer.transfer_display_name)
+                ] = ""
+
+                if conv_subplot := self._conv_subplots.get(interface_name):
+                    data_index_map[transfer.data_index] = (conv_subplot, iconv)
+                    # Add a new series list to y_data, and label to series_labels
+                    # Both will be at position iconv of respective lists
+                    # conv_subplot.y_data.append([])
+                    conv_subplot.series_labels.append(transfer.transfer_display_name)
+                    iconv += 1
+            else:
+                transfer_value_subplot = self._transfer_subplots.get(
+                    (interface_name, transfer_key[0], transfer_key[1])
+                )
+                if transfer_value_subplot:
+                    value_type = (
+                        "Sum"
+                        if transfer.series_type == SeriesType.SUM
+                        else "Weighted Average"
+                    )
+                    transfer_value_subplot.title = transfer_value_subplot.title.replace(
+                        "<VALUETYPE>", value_type
+                    )
+                    itransval = transfer_value_line_count.get(transfer_key, 0)
+                    if not transfer.line_suffixes:
+                        data_index_map[transfer.data_index] = (
+                            transfer_value_subplot,
+                            itransval,
+                        )
+                        transfer_value_subplot.series_labels.append(
+                            transfer.participant_display_name
+                        )
+                        itransval += 1
+                        transfer_value_line_count[transfer_key] = itransval
+                    else:
+                        for i, suffix in enumerate(transfer.line_suffixes):
+                            data_index_map[transfer.data_index + i] = (
+                                transfer_value_subplot,
+                                itransval + i,
+                            )
+                            transfer_value_subplot.series_labels.append(
+                                transfer.participant_display_name + suffix
+                            )
+                        transfer_value_line_count[transfer_key] = itransval + len(
+                            transfer.line_suffixes
+                        )
+
+        # This will be what allows us to update subplot data as new data received
+        self._data_index_map[interface_name] = data_index_map

ansys/systemcoupling/core/charts/plotter.py

@@ -0,0 +1,343 @@
+# 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.
+
+import math
+import sys
+from typing import Callable, Optional, Union
+
+from matplotlib.animation import FuncAnimation
+from matplotlib.figure import Figure
+from matplotlib.lines import Line2D
+import matplotlib.pyplot as plt
+
+from ansys.systemcoupling.core.charts.chart_datatypes import (
+    InterfaceInfo,
+    SeriesData,
+    TimestepData,
+)
+from ansys.systemcoupling.core.charts.plotdefinition_manager import (
+    PlotDefinitionManager,
+)
+
+
+def _process_timestep_data(
+    timestep_data: TimestepData,
+) -> tuple[list[int], list[float]]:
+    if not timestep_data.timestep:
+        return [], []
+
+    # TODO: for a dynamically updating case, it should be possible to do a partial update.
+    time_indexes = [0]
+    times = [None]
+    curr_step = timestep_data.timestep[0]
+    for i, step in enumerate(timestep_data.timestep):
+        time = timestep_data.time[i]
+        if step == curr_step:
+            # Still in the same step, so update
+            times[-1] = time
+            time_indexes[-1] = i
+        else:
+            # New step
+            times.append(time)
+            time_indexes.append(i)
+            curr_step = step
+    return (time_indexes, times)
+
+
+def _calc_new_ylimits_linear(
+    ynew: list[float], old_lim: Optional[tuple[float, float]]
+) -> tuple[float, float]:
+    resize_tol = 0.02
+    resize_delta = 0.1
+
+    min_y = min(ynew)
+    max_y = max(ynew)
+
+    # Try to do something reasonable while we still don't have much data.
+    # Try to account for case where we don't have much data and range & value both zero.
+    data_range = min_y if abs(max_y - min_y) < 1.0e-7 else max_y - min_y
+    data_range = abs(data_range)
+    if data_range < 1.0e-7:
+        delta_limits = 1.0e-7
+    else:
+        delta_limits = resize_delta * data_range
+
+    if old_lim is None:
+        # First update - force calculation
+        old_l = min_y + 1
+        old_u = max_y - 1
+    else:
+        new_l, new_u = old_l, old_u = old_lim
+
+    if min_y < old_l + resize_tol * data_range:
+        new_l = min_y - delta_limits
+    if max_y > old_u - resize_tol * data_range:
+        new_u = max_y + delta_limits
+
+    return new_l, new_u
+
+
+def _calc_new_ylimits_log(
+    ynew: list[float], old_lim: Optional[tuple[float, float]]
+) -> tuple[float, float]:
+
+    min_y = min(ynew)
+    max_y = max(ynew)
+
+    if old_lim is not None:
+        new_l, new_u = old_lim
+
+    if old_lim is None or min_y < old_lim[0]:
+        log_l = math.log10(min_y)
+        exponent = math.floor(log_l)
+        new_l = math.pow(10.0, exponent)
+    if old_lim is None or max_y > old_lim[1]:
+        log_u = math.log10(max_y)
+        exponent = math.ceil(log_u)
+        new_u = math.pow(10.0, exponent)
+        # We do this in the GUI - is it needed?
+        new_u *= 1.0 + 1.0e-7
+
+    return new_l, new_u
+
+
+def _update_xy_data(
+    time_info: Optional[tuple[list[int], list[float]]],
+    x_curr,  # ArrayLike
+    y_curr,  # ArrayLike
+    series_data: list[float],
+    new_start_index: int,
+) -> tuple[Union[list[float], list[int]], list[float]]:
+
+    new_total_data_len = new_start_index + len(series_data)
+    x_new = []
+    y_new = []
+    if time_info:
+        time_indexes, time_values = time_info
+        # IMPORTANT: Assume that time data is updated ahead of any series data
+        # This means that (new_data_len - 1) should always be <= maximum known
+        # time index.
+        # time_indexes[-1] is the latest known 0-based iteration index that belongs
+        # to the latest timestep.
+        for i, time_iter in enumerate(time_indexes):
+            # Straight copy if not overlapping with new data yet
+            if time_iter < new_start_index:
+                x_new.append(time_values[i])
+                y_new.append(y_curr[i])
+
+            # Don't assume we have data yet for all known timesteps
+            elif time_iter < new_total_data_len:
+                x_new.append(time_values[i])
+                y_new.append(series_data[time_iter - new_start_index])
+    else:
+        for i in range(new_total_data_len):
+            if i < new_start_index:
+                x_new.append(x_curr[i])
+                y_new.append(y_curr[i])
+            else:
+                x_new.append(i + 1)
+                y_new.append(series_data[i - new_start_index])
+    return (x_new, y_new)
+
+
+# TODO: Only handles one interface at the moment! Generalise to multiple
+class Plotter:
+    def __init__(
+        self,
+        mgr: PlotDefinitionManager,
+        request_update: Optional[Callable[[], None]] = None,
+    ):
+        self._mgr = mgr
+        self._request_update = request_update
+
+        self._fig: Figure = plt.figure()
+        self._subplot_lines: list[list[Line2D]] = []
+        self._subplot_limits_set: list[bool] = []
+        self._metadata: Optional[InterfaceInfo] = None
+
+        # Empty if not transient:
+        self._times: list[float] = []  # Time value at each time step
+        self._time_indexes: list[int] = []  # Iteration to take value at time i from
+
+    def set_metadata(self, metadata: InterfaceInfo):
+        self._metadata = metadata
+        self._mgr.set_metadata(metadata)
+        # We now have enough information to create the (empty) plots
+        self._init_plots()
+
+    def set_timestep_data(self, timestep_data: TimestepData):
+
+        if timestep_data.timestep and not self._metadata.is_transient:
+            raise RuntimeError("Attempt to set timestep data on non-transient case")
+
+        self._time_indexes, self._times = _process_timestep_data(timestep_data)
+
+    def update_line_series(self, series_data: SeriesData):
+        """Update the line series determined by the provided ``series_data`` with the
+        incremental data that it contains.
+
+        The ``series_data`` contains the "start index" in the full series, the index
+        to start writing the new data.
+        """
+        if not self._metadata:
+            raise RuntimeError(
+                "Attempt to add series data to plot before metadata provided."
+            )
+
+        trans = self._metadata.transfer_info[series_data.transfer_index]
+        offset = (
+            series_data.component_index
+            if series_data.component_index is not None
+            else 0
+        )
+        subplot_defn, subplot_line_index = self._mgr.subplot_for_data_index(
+            self._metadata.name, trans.data_index + offset
+        )
+        if subplot_defn is None:
+            # This can happen if the list of plots being show is filtered.
+            return
+
+        subplot_line = self._subplot_lines[subplot_defn.index][subplot_line_index]
+
+        # We don't assume that all provided series_data are fully up to
+        # date with the latest iteration or timestep that pertains globally
+        # over all plots.
+
+        if len(series_data.data) == 0:
+            return
+
+        x_curr, y_curr = subplot_line.get_data()
+        x_new, y_new = _update_xy_data(
+            (self._time_indexes, self._times) if self._times else None,
+            x_curr,
+            y_curr,
+            series_data.data,
+            series_data.start_index,
+        )
+
+        self.update_limits(subplot_defn.index, subplot_defn.is_log_y, x_new, y_new)
+        subplot_line.set_data(x_new, y_new)
+
+    def update_limits(self, subplot_index, is_log_y, x_new, y_new):
+        axes = self._fig.axes[subplot_index]
+
+        are_limits_initialised = self._subplot_limits_set[subplot_index]
+
+        old_xlim = (0, 0)
+        old_ylim = None
+        if are_limits_initialised:
+            old_xlim = axes.get_xlim()
+            old_ylim = axes.get_ylim()
+
+        new_ylimits = (
+            _calc_new_ylimits_log(y_new, old_ylim)
+            if is_log_y
+            else _calc_new_ylimits_linear(y_new, old_ylim)
+        )
+
+        new_xlimits = old_xlim
+        if self._times:
+            if x_new[-1] >= old_xlim[1] * 0.95:
+                new_xlimits = (0.0, x_new[-1] * 1.1)
+        else:
+            if len(x_new) >= old_xlim[1] - 1:
+                new_xlimits = (1, len(x_new) + 1)
+
+        axes.set_xlim(new_xlimits)
+        axes.set_ylim(new_ylimits)
+
+        self._subplot_limits_set[subplot_index] = True
+
+    def close(self):
+        if self._fig:
+            plt.close(self._fig)
+
+    def show_plot(self, noblock=False):
+        if noblock:
+            plt.ion()
+        plt.show()
+
+    def show_animated(self):
+        # NB: if using the wait_for_metadata() approach
+        # supported by MessageDispatcher, do it here like
+        # this (assume the wait function is stored as an
+        # attribute):
+        #
+        # assert self._wait_for_metadata is not None
+        # metadata = self._wait_for_metadata()
+        # if metadata is not None:
+        #     self.set_metadata(metadata)
+        # else:
+        #     return
+        assert self._request_update is not None
+
+        self.ani = FuncAnimation(
+            self._fig,
+            self._update_animation,
+            # frames=x_axis_pts,
+            save_count=sys.maxsize,
+            # init_func=self._init_plots,
+            blit=False,
+            interval=200,
+            repeat=False,
+        )
+        plt.show()
+
+    def _update_animation(self, frame: int):
+        # print("calling update animation")
+        return self._request_update()
+
+    def _init_plots(self):
+        # plt.ion()
+        nrow, ncol = self._mgr.get_layout()
+        self._fig.subplots(nrow, ncol, gridspec_kw={"hspace": 0.5})
+        subplot_defns = self._mgr.subplots
+        if len(subplot_defns) != 1 and len(subplot_defns) % 2 == 1:
+            self._fig.delaxes(self._fig.axes[-1])
+
+        # Add labels and legends
+        for axes, subplot_defn in zip(self._fig.axes, subplot_defns):
+            axes.set_title(subplot_defn.title, fontsize=8)
+            if subplot_defn.is_log_y:
+                axes.set_yscale("log")
+            axes.set_xlabel(subplot_defn.x_axis_label, fontsize=8)
+            axes.set_ylabel(subplot_defn.y_axis_label, fontsize=8)
+            lines = []
+            for label in subplot_defn.series_labels:
+                (ln,) = axes.plot([], [], label=label)
+                lines.append(ln)
+            axes.legend(fontsize=6)
+
+            # Set arbitrary axes limits
+            if self._metadata.is_transient:
+                axes.set_xlim(0.0, 1.0)
+            else:
+                axes.set_xlim(1, 5)
+            if subplot_defn.is_log_y:
+                axes.set_ylim(1e-20, 1)
+            else:
+                axes.set_ylim(0, 1.0)
+
+            # Keep hold of lines so that we can assign data when it's available
+            self._subplot_lines.append(lines)
+            # The limits on this subplot are essentially unset until we start getting data
+            self._subplot_limits_set.append(False)

ansys/systemcoupling/core/client/grpc_client.py

@@ -119,6 +119,7 @@ class SycGrpc(object):
         working_dir = kwargs.pop("working_dir", None)
         port = kwargs.pop("port", None)
         version = kwargs.pop("version", None)
+        start_output = kwargs.pop("start_output", None)
 
         if os.environ.get("SYC_LAUNCH_CONTAINER") == "1":
             mounted_from = working_dir if working_dir else "./"
@@ -137,6 +138,8 @@ class SycGrpc(object):
             )
             LOG.debug("...started")
             self._connect(_LOCALHOST_IP, port)
+        if start_output:
+            self.start_output()
 
     def start_container_and_connect(
         self,
@@ -153,7 +156,7 @@ class SycGrpc(object):
         LOG.debug("...started")
         self._connect(_LOCALHOST_IP, port)
 
-    def start_pim_and_connect(self, version: str = None):
+    def start_pim_and_connect(self, version: str = None, start_output: bool = False):
         """Start PIM-managed instance.
 
         Currently for internal use only.
@@ -171,6 +174,8 @@ class SycGrpc(object):
         self.__pim_instance = instance
         channel = instance.build_grpc_channel()
         self._connect(channel=channel)
+        if start_output:
+            self.start_output()
 
     def upload_file(self, *args, **kwargs):
         """Supports file upload to remote instance.