RSSeismicScripting 3.0.0__py3-none-any.whl

rsseismic/Application.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import logging
+
+from rsseismic._application_paths import getInstalledExecutablePath
+from rsseismic._client import Client, DEFAULT_SCRIPTING_PORT
+from rsseismic.ApplicationManager import ApplicationManager
+from rsseismic._rpc_helpers import require_success
+from rsseismic.exceptions import ScriptingError
+from rsseismic.generatedFiles import ApplicationService_pb2 as ApplicationService_pb2
+from rsseismic.generatedFiles import ApplicationService_pb2_grpc as ApplicationService_pb2_grpc
+from rsseismic._batch_compute import (
+    BatchComputeJobResult,
+    BatchComputeResult,
+    run_batch_compute,
+)
+from rsseismic.Model import Model
+
+
+class RSSeismicApplication:
+    """
+    Entry point for connecting to a running RSSeismic scripting server.
+
+    Mirrors RS3's RS3Modeler: connect on a port, open projects, return Model proxies.
+    Use startApplication() to launch RSSeismic with -startScriptingServer when it is
+    not already running.
+    """
+
+    def __init__(self, port: int = DEFAULT_SCRIPTING_PORT, host: str = "localhost"):
+        self._client = Client(port=port, host=host)
+        self._port = port
+        self._host = host
+
+    @property
+    def port(self) -> int:
+        return self._port
+
+    @property
+    def client(self) -> Client:
+        return self._client
+
+    @classmethod
+    def startApplication(
+        cls,
+        port: int = DEFAULT_SCRIPTING_PORT,
+        overridePathToExecutable: str | None = None,
+        timeout: float = ApplicationManager.defaultTimeout,
+    ) -> None:
+        """
+        Launch RSSeismic and wait until the scripting server on port accepts ping.
+
+        Args:
+            port: Scripting port (49152–65535). Same value as DEFAULT_SCRIPTING_PORT / 60058.
+            overridePathToExecutable: Full path to RSSeismic.exe. When omitted, the latest
+                RSSeismic install is resolved from the Windows registry.
+            timeout: Seconds to wait for the server to become reachable.
+
+        Raises:
+            ValueError: port out of range
+            RuntimeError: port occupied, executable not found, or registry lookup failed
+            TimeoutError: server not ready within timeout
+        """
+        executable_path = (
+            overridePathToExecutable
+            if overridePathToExecutable
+            else getInstalledExecutablePath()
+        )
+        app_manager = ApplicationManager()
+        app_logger = logging.getLogger("Rocscience.RSSeismic")
+        app_manager.startApplication(
+            executable_path,
+            port,
+            cls._verifyServerRunning,
+            app_logger,
+            timeout,
+        )
+
+    @staticmethod
+    def _verifyServerRunning(port: int) -> None:
+        client = Client(port=port)
+        try:
+            client.ping()
+        finally:
+            client.closeConnection()
+
+    def ping(self) -> None:
+        """Verify the scripting server is reachable."""
+        self._client.ping()
+
+    def getMaxConcurrentAnalyses(self) -> int:
+        """
+        Return the effective maxConcurrentAnalyses from RSSeismic preferences.
+
+        This is the within-project cap on simultaneous engine runs used during
+        RunCompute. Batch parallel_degree capping uses this value when available.
+        """
+        stub = ApplicationService_pb2_grpc.ApplicationServiceStub(self._client.channel)
+        request = ApplicationService_pb2.GetMaxConcurrentAnalysesRequest()
+        response = self._client.callFunction(stub.GetMaxConcurrentAnalyses, request)
+        return int(response.maxConcurrentAnalyses)
+
+    def setMaxConcurrentAnalyses(self, maxConcurrentAnalyses: int) -> int:
+        """
+        Set maxConcurrentAnalyses in RSSeismic preferences (within-project engine cap).
+
+        Values are clamped to 1..256, matching the Preferences UI. Returns the effective
+        value after save (same semantics as getMaxConcurrentAnalyses).
+        """
+        stub = ApplicationService_pb2_grpc.ApplicationServiceStub(self._client.channel)
+        request = ApplicationService_pb2.SetMaxConcurrentAnalysesRequest(
+            maxConcurrentAnalyses=maxConcurrentAnalyses,
+        )
+        response = self._client.callFunction(stub.SetMaxConcurrentAnalyses, request)
+
+        if not response.success:
+            raise ScriptingError(
+                response.errorMessage or "SetMaxConcurrentAnalyses failed."
+            )
+
+        return int(response.maxConcurrentAnalyses)
+
+    def openFile(self, path: str) -> Model:
+        """Open a DeepSoil project file and return a Model handle."""
+        stub = ApplicationService_pb2_grpc.ApplicationServiceStub(self._client.channel)
+        request = ApplicationService_pb2.OpenFileRequest(fileName=path)
+        response = self._client.callFunction(stub.OpenFile, request)
+        require_success(response, "OpenFile")
+
+        if not response.modelID:
+            raise ScriptingError("OpenFile succeeded but returned an empty modelID.")
+
+        return Model(self._client, response.modelID)
+
+    def newProject(self) -> Model:
+        """Create a blank project with default settings and return a Model handle."""
+        stub = ApplicationService_pb2_grpc.ApplicationServiceStub(self._client.channel)
+        request = ApplicationService_pb2.NewProjectRequest()
+        response = self._client.callFunction(stub.NewProject, request)
+
+        if not response.success:
+            raise ScriptingError("NewProject failed.")
+
+        if not response.modelID:
+            raise ScriptingError("NewProject succeeded but returned an empty modelID.")
+
+        return Model(self._client, response.modelID)
+
+    def runBatchCompute(
+        self,
+        file_paths: list[str],
+        motion_names: list[str] | None = None,
+        *,
+        parallel_degree: int = 1,
+        max_concurrent_analyses: int | None = None,
+        timeout: float | None = None,
+        close_save_project: bool = False,
+        continue_on_error: bool = True,
+    ) -> BatchComputeResult:
+        """
+        Run compute for many project files (open → motion selection → compute → close).
+
+        Motion selection applies to the open session only; it is not stored in the
+        project file. Each job calls setMotionSelection before runCompute.
+
+        Args:
+            file_paths: Project files to process (.rsseismicfile). Duplicate paths are omitted.
+            motion_names: Motions to select for every project. When None, each project keeps
+                its current selection or uses the first available motion.
+            parallel_degree: How many projects may run at once (cross-project only). Capped
+                using maxConcurrentAnalyses from RSSeismic preferences when available.
+            max_concurrent_analyses: When set, applies this within-project engine cap for the
+                batch via setMaxConcurrentAnalyses and restores the previous preference after
+                the batch. When None, uses getMaxConcurrentAnalyses().
+            timeout: Optional RunCompute deadline in seconds for each project.
+            close_save_project: When True, save each project on close.
+            continue_on_error: When False, stop starting new jobs after the first failure
+                (in-flight jobs may still finish).
+
+        Returns:
+            BatchComputeResult with per-file outcomes in input order.
+        """
+        return run_batch_compute(
+            self,
+            file_paths,
+            motion_names,
+            parallel_degree=parallel_degree,
+            max_concurrent_analyses=max_concurrent_analyses,
+            timeout=timeout,
+            close_save_project=close_save_project,
+            continue_on_error=continue_on_error,
+            logger=logging.getLogger("Rocscience.RSSeismic"),
+        )
+
+    def close(self) -> None:
+        """Close the gRPC connection."""
+        self._client.closeConnection()

rsseismic/ApplicationManager.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+import time
+from logging import Logger
+from typing import Callable
+
+from multiprocessing.connection import Listener
+
+
+class ApplicationManager:
+    minimumPort = 49152
+    maximumPort = 65535
+    defaultTimeout = 120.0
+
+    def startApplication(
+        self,
+        pathToExecutable: str,
+        port: int,
+        isServerRunning: Callable[[int], None],
+        logger: Logger,
+        timeout: float = defaultTimeout,
+    ) -> None:
+        """
+        Starts the application specified by pathToExecutable with ``-startScriptingServer`` on the given port.
+        Returns when the scripting server is ready to accept requests.
+
+        Args:
+            pathToExecutable: Full path to the RSSeismic executable to start.
+            port: Port number for the scripting server (49152–65535).
+            isServerRunning: Callable invoked to verify the server on ``port`` is reachable.
+            logger: Logger used during startup; logging is suppressed while polling the server.
+            timeout: Seconds to wait for the server to become ready.
+
+        Raises:
+            ValueError: port outside 49152–65535
+            RuntimeError: port occupied or executable missing
+            TimeoutError: server not ready within timeout
+        """
+        if port < self.minimumPort or port > self.maximumPort:
+            msg = f"port must be in the range {self.minimumPort} to {self.maximumPort}"
+            logger.error(msg)
+            raise ValueError(msg)
+
+        if not os.path.isfile(pathToExecutable):
+            msg = f"executable not found: {pathToExecutable}"
+            logger.error(msg)
+            raise RuntimeError(msg)
+
+        if not self.isPortAvailable(port):
+            msg = f"port number {port} is occupied. Please choose another port."
+            logger.error(msg)
+            raise RuntimeError(msg)
+
+        logger.info(
+            "Starting RSSeismic at %s with scripting server on port %s...",
+            pathToExecutable,
+            port,
+        )
+        popen_kwargs: dict = {
+            "args": [pathToExecutable, "-startScriptingServer", str(port)],
+            "start_new_session": True,
+        }
+        if sys.platform == "win32":
+            popen_kwargs["creationflags"] = subprocess.DETACHED_PROCESS
+
+        subprocess.Popen(**popen_kwargs)
+        self._tryToConnectToServer(port, isServerRunning, timeout, logger)
+
+    @staticmethod
+    def isPortAvailable(port: int) -> bool:
+        listener = None
+        try:
+            listener = Listener(("localhost", port), "AF_INET")
+            return True
+        except Exception:
+            return False
+        finally:
+            if listener is not None:
+                listener.close()
+
+    def _tryToConnectToServer(
+        self,
+        port: int,
+        isServerRunning: Callable[[int], None],
+        timeout: float,
+        logger: Logger,
+    ) -> None:
+        start_time = time.time()
+
+        while True:
+            if timeout and (time.time() - start_time) > timeout:
+                msg = "RSSeismic did not start the scripting server within the given timeout."
+                logger.error(msg)
+                raise TimeoutError(msg)
+
+            try:
+                logger.debug("Trying to connect to the scripting server...")
+                previous_disabled = logger.disabled
+                logger.disabled = True
+                try:
+                    isServerRunning(port)
+                finally:
+                    logger.disabled = previous_disabled
+                logger.debug("Connected to scripting server.")
+                return
+            except Exception:
+                time.sleep(0.5)

rsseismic/BedrockLayer.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from rsseismic._client import Client
+from rsseismic._proxyObject import _ProxyObject
+from rsseismic.generatedFiles import BedrockLayerDataService_pb2_grpc as BedrockLayerDataService_pb2_grpc
+from rsseismic.properties._PropertyAccessor import ProjectScopedPropertyAccessor
+from rsseismic.properties.bedrockLayer._generated import BedrockLayerPropertiesMixin
+
+
+class BedrockLayer(_ProxyObject, BedrockLayerPropertiesMixin):
+    """
+    Read and edit bedrock layer properties for a profile.
+
+    Obtain an instance from ``model.Profiles.getBedrockLayerProxy(profileName)``.
+
+    Bedrock thickness cannot be changed through this object; it is calculated from
+    the soil layers above bedrock. To read thickness, use
+    ``model.Profiles.getBedrockLayer(profileName).thickness``.
+    """
+
+    def __init__(self, client: Client, modelId: str, layerId: str):
+        super().__init__(client, layerId)
+        self.modelId = modelId
+        stub = BedrockLayerDataService_pb2_grpc.BedrockLayerDataServiceStub(self._client.channel)
+        self.Data = ProjectScopedPropertyAccessor(client, modelId, layerId, stub)
+
+    @property
+    def layerId(self) -> str:
+        return self._objectId

rsseismic/MeanProfile.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rsseismic._client import Client
+from rsseismic._proto_converters import (
+    from_mean_profile_append_layers_response,
+    from_mean_profile_bedrock_layer_entry,
+    from_mean_profile_delete_layer_response,
+    from_mean_profile_insert_layer_response,
+    from_mean_profile_move_layer_response,
+    from_mean_profile_response,
+    from_mean_profile_soil_layer_entry,
+)
+from rsseismic._proxyObject import _ProxyObject
+from rsseismic._rpc_helpers import require_success
+from rsseismic.generatedFiles import MeanProfileService_pb2 as MeanProfileService_pb2
+from rsseismic.generatedFiles import MeanProfileService_pb2_grpc as MeanProfileService_pb2_grpc
+from rsseismic.types import (
+    BedrockLayerSummary,
+    MeanProfileAppendLayersResult,
+    MeanProfileDeleteLayerResult,
+    MeanProfileInsertLayerResult,
+    MeanProfileMoveLayerResult,
+    MeanProfileSummary,
+    SoilLayerSummary,
+)
+
+if TYPE_CHECKING:
+    from rsseismic.MeanProfileSoilLayer import MeanProfileSoilLayer
+
+
+class MeanProfile(_ProxyObject):
+    """
+    Template mean profile for automatic profile generation.
+
+    When automatic profile generation is enabled, configure this profile before
+    calling ``Model.generateProfiles()``. The individual profiles created by that
+    step are based on this template, not on the profiles under ``model.Profiles``.
+
+    Use ``listSoilLayers``, ``getSoilLayer``, ``insertLayerBefore``, and related
+    methods to edit the template. To change layer properties, use the
+    ``MeanProfileSoilLayer`` returned by ``getSoilLayer`` (including reference
+    curves via ``layer.ReferenceCurve``).
+    """
+
+    def __init__(self, client: Client, modelId: str):
+        super().__init__(client, modelId)
+        self.modelId = modelId
+        self._mean_profile_service = MeanProfileService_pb2_grpc.MeanProfileServiceStub(
+            self._client.channel
+        )
+
+    def getMeanProfile(self) -> MeanProfileSummary:
+        """Return summary information for the mean profile."""
+        request = MeanProfileService_pb2.GetMeanProfileRequest(modelID=self._objectId)
+        response = self._client.callFunction(self._mean_profile_service.GetMeanProfile, request)
+        require_success(response, "GetMeanProfile")
+        return from_mean_profile_response(response)
+
+    def listSoilLayers(self) -> list[SoilLayerSummary]:
+        """List soil layers on the mean profile."""
+        request = MeanProfileService_pb2.ListSoilLayersRequest(modelID=self._objectId)
+        response = self._client.callFunction(self._mean_profile_service.ListSoilLayers, request)
+        require_success(response, "ListSoilLayers")
+        return [from_mean_profile_soil_layer_entry(layer) for layer in response.layers]
+
+    def getBedrockLayer(self) -> BedrockLayerSummary:
+        """Return the bedrock layer on the mean profile."""
+        request = MeanProfileService_pb2.GetBedrockLayerRequest(modelID=self._objectId)
+        response = self._client.callFunction(self._mean_profile_service.GetBedrockLayer, request)
+        require_success(response, "GetBedrockLayer")
+        return from_mean_profile_bedrock_layer_entry(response.bedrock)
+
+    def getSoilLayer(self, layerId: str) -> MeanProfileSoilLayer:
+        """Return a property proxy for a mean-profile soil layer GUID."""
+        from rsseismic.MeanProfileSoilLayer import MeanProfileSoilLayer
+
+        return MeanProfileSoilLayer(self._client, self._objectId, layerId)
+
+    def insertLayerBefore(
+        self,
+        referenceLayerID: str,
+    ) -> MeanProfileInsertLayerResult:
+        """
+        Insert a soil layer before referenceLayerID.
+
+        referenceLayerID may be a soil layer GUID or the bedrock layer GUID
+        (insert before bedrock appends a layer).
+        """
+        request = MeanProfileService_pb2.InsertLayerBeforeRequest(
+            modelID=self._objectId,
+            referenceLayerID=referenceLayerID,
+        )
+        response = self._client.callFunction(
+            self._mean_profile_service.InsertLayerBefore,
+            request,
+        )
+        require_success(response, "InsertLayerBefore")
+        return from_mean_profile_insert_layer_response(response)
+
+    def insertLayerAfter(
+        self,
+        referenceLayerID: str,
+    ) -> MeanProfileInsertLayerResult:
+        """Insert a soil layer after a soil layer GUID."""
+        request = MeanProfileService_pb2.InsertLayerAfterRequest(
+            modelID=self._objectId,
+            referenceLayerID=referenceLayerID,
+        )
+        response = self._client.callFunction(
+            self._mean_profile_service.InsertLayerAfter,
+            request,
+        )
+        require_success(response, "InsertLayerAfter")
+        return from_mean_profile_insert_layer_response(response)
+
+    def appendLayers(self, count: int = 1) -> MeanProfileAppendLayersResult:
+        """Append one or more soil layers before bedrock."""
+        request = MeanProfileService_pb2.AppendLayersRequest(
+            modelID=self._objectId,
+            count=count,
+        )
+        response = self._client.callFunction(self._mean_profile_service.AppendLayers, request)
+        require_success(response, "AppendLayers")
+        return from_mean_profile_append_layers_response(response)
+
+    def deleteLayer(self, layerID: str) -> MeanProfileDeleteLayerResult:
+        """Delete a mean-profile soil layer. At least one soil layer must remain."""
+        request = MeanProfileService_pb2.DeleteLayerRequest(
+            modelID=self._objectId,
+            layerID=layerID,
+        )
+        response = self._client.callFunction(self._mean_profile_service.DeleteLayer, request)
+        require_success(response, "DeleteLayer")
+        return from_mean_profile_delete_layer_response(response)
+
+    def duplicateLayer(
+        self,
+        sourceLayerID: str,
+        insertAfter: bool = True,
+    ) -> MeanProfileInsertLayerResult:
+        """Duplicate a mean-profile soil layer before or after the source layer."""
+        request = MeanProfileService_pb2.DuplicateLayerRequest(
+            modelID=self._objectId,
+            sourceLayerID=sourceLayerID,
+            insertAfter=insertAfter,
+        )
+        response = self._client.callFunction(
+            self._mean_profile_service.DuplicateLayer,
+            request,
+        )
+        require_success(response, "DuplicateLayer")
+        return from_mean_profile_insert_layer_response(response)
+
+    def moveLayer(
+        self,
+        layerID: str,
+        newIndex1Based: int,
+    ) -> MeanProfileMoveLayerResult:
+        """Move a mean-profile soil layer to a new 1-based index."""
+        request = MeanProfileService_pb2.MoveLayerRequest(
+            modelID=self._objectId,
+            layerID=layerID,
+            newIndex1Based=newIndex1Based,
+        )
+        response = self._client.callFunction(self._mean_profile_service.MoveLayer, request)
+        require_success(response, "MoveLayer")
+        return from_mean_profile_move_layer_response(response)

rsseismic/MeanProfileSoilLayer.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from rsseismic._client import Client
+from rsseismic._proxyObject import _ProxyObject
+from rsseismic._rpc_helpers import require_success
+from rsseismic.generatedFiles import MeanProfileSoilLayerDataService_pb2 as MeanProfileSoilLayerDataService_pb2
+from rsseismic.generatedFiles import MeanProfileSoilLayerDataService_pb2_grpc as MeanProfileSoilLayerDataService_pb2_grpc
+from rsseismic.properties._PropertyAccessor import ProjectScopedPropertyAccessor
+from rsseismic.properties.meanProfileSoilLayer._generated import MeanProfileSoilLayerPropertiesMixin
+from rsseismic.ReferenceCurve import ReferenceCurve
+
+
+def _to_vary_with_depth_points(
+    points: list[tuple[float, float]],
+) -> list[MeanProfileSoilLayerDataService_pb2.VaryWithDepthPoint]:
+    return [
+        MeanProfileSoilLayerDataService_pb2.VaryWithDepthPoint(depth=depth, value=value)
+        for depth, value in points
+    ]
+
+
+def _from_vary_with_depth_points(
+    points: list[MeanProfileSoilLayerDataService_pb2.VaryWithDepthPoint],
+) -> list[tuple[float, float]]:
+    return [(point.depth, point.value) for point in points]
+
+
+class MeanProfileSoilLayer(_ProxyObject, MeanProfileSoilLayerPropertiesMixin):
+    """
+    Read and edit properties for one soil layer on the mean profile template.
+
+    Obtain an instance from ``model.MeanProfile.getSoilLayer(layerId)``. Layer IDs
+    come from ``model.MeanProfile.listSoilLayers()``.
+
+    Use the generated ``get*`` / ``set*`` helpers for scalar layer properties. When
+    shear wave velocity or shear strength varies with depth, set the variation mode
+    first, then use ``getShearWaveValues`` / ``setShearWaveValues`` or
+    ``getShearStrengthValues`` / ``setShearStrengthValues`` for the depth table.
+
+    Reference curves are edited through ``layer.ReferenceCurve``. Unlike regular
+    profile layers, ``ReferenceCurve.generateReferenceCurve()`` is not available here;
+    set curve properties and points on ``ReferenceCurve`` directly.
+    """
+
+    def __init__(self, client: Client, modelId: str, layerId: str):
+        super().__init__(client, layerId)
+        self.modelId = modelId
+        stub = MeanProfileSoilLayerDataService_pb2_grpc.MeanProfileSoilLayerDataServiceStub(
+            self._client.channel
+        )
+        self.Data = ProjectScopedPropertyAccessor(client, modelId, layerId, stub)
+        self.ReferenceCurve = ReferenceCurve(client, modelId, layerId)
+        self._service = stub
+
+    @property
+    def layerId(self) -> str:
+        return self._objectId
+
+    def getShearWaveValues(self) -> list[tuple[float, float]]:
+        """
+        Return vary-with-depth shear wave velocity points as (depth, value) pairs.
+
+        Requires shearWaveVelocityVariation = Vary_With_Depth.
+        """
+        request = MeanProfileSoilLayerDataService_pb2.GetShearWaveValuesRequest(
+            projectId=self.modelId,
+            layerID=self._objectId,
+        )
+        response = self._client.callFunction(self._service.GetShearWaveValues, request)
+        require_success(response, "GetShearWaveValues")
+        return _from_vary_with_depth_points(list(response.points))
+
+    def setShearWaveValues(self, points: list[tuple[float, float]]) -> None:
+        """
+        Set vary-with-depth shear wave velocity points from (depth, value) pairs.
+
+        Requires shearWaveVelocityVariation = Vary_With_Depth. The server requires
+        at least two points.
+        """
+        if not points:
+            raise ValueError("At least one vary-with-depth point is required.")
+        request = MeanProfileSoilLayerDataService_pb2.SetShearWaveValuesRequest(
+            projectId=self.modelId,
+            layerID=self._objectId,
+            points=_to_vary_with_depth_points(points),
+        )
+        response = self._client.callFunction(self._service.SetShearWaveValues, request)
+        require_success(response, "SetShearWaveValues")
+
+    def getShearStrengthValues(self) -> list[tuple[float, float]]:
+        """
+        Return vary-with-depth shear strength points as (depth, value) pairs.
+
+        Requires shearStrengthVariation = Vary_With_Depth.
+        """
+        request = MeanProfileSoilLayerDataService_pb2.GetShearStrengthValuesRequest(
+            projectId=self.modelId,
+            layerID=self._objectId,
+        )
+        response = self._client.callFunction(self._service.GetShearStrengthValues, request)
+        require_success(response, "GetShearStrengthValues")
+        return _from_vary_with_depth_points(list(response.points))
+
+    def setShearStrengthValues(self, points: list[tuple[float, float]]) -> None:
+        """
+        Set vary-with-depth shear strength points from (depth, value) pairs.
+
+        Requires shearStrengthVariation = Vary_With_Depth. The server requires
+        at least two points.
+        """
+        if not points:
+            raise ValueError("At least one vary-with-depth point is required.")
+        request = MeanProfileSoilLayerDataService_pb2.SetShearStrengthValuesRequest(
+            projectId=self.modelId,
+            layerID=self._objectId,
+            points=_to_vary_with_depth_points(points),
+        )
+        response = self._client.callFunction(self._service.SetShearStrengthValues, request)
+        require_success(response, "SetShearStrengthValues")