RS3Scripting 4.42.0__py3-none-any.whl

rs3/results/SolidResults.py

@@ -0,0 +1,206 @@
+from typing import Optional, Union
+import grpc
+
+import rs3.generatedFiles.SolidsResultsQueryService_pb2_grpc as SolidsResultsQueryService_pb2_grpc
+import rs3.generatedFiles.SolidsResultsQueryService_pb2 as SolidsResultsQueryService_pb2
+
+from rs3._proxyObject import _ProxyObject
+from rs3._client import Client
+
+from rs3.Geometry import Cube, Cylinder, Sphere
+from rs3.results.SolidElementResults import SolidElementResults
+from rs3.results.SolidNodalResults import SolidNodalResults, SolidsDataType
+
+class SolidResults(_ProxyObject):
+    '''
+    Entry point to query solid nodal/element results for a given stage and SRF.
+
+    Parameters:
+        stageNumber (int): 1-based stage index.
+        srfResultIndex (int): 0-based SRF value index. 0 is to query SRF-None values.
+
+    Notes:
+        - entityName is trimmed; empty strings are ignored.
+        - region=None leaves the proto field unset (service returns all).
+        - Exceptions from the underlying service are propagated as-is by the client.
+
+    Examples:
+        See :ref:`solid_result_example`.
+    '''
+    def __init__(self, client: Client, projectId: str, stageNumber: int, srfResultIndex: int, requiredDataTypes: Optional[set[SolidsDataType]] = None):
+        super().__init__(client, projectId)
+        self._queryService = SolidsResultsQueryService_pb2_grpc.SolidResultsQueryServiceStub(self._client.channel)
+        self._stageNumber = stageNumber
+        self._srfResultIndex = srfResultIndex
+        self._requiredDataTypes = requiredDataTypes
+
+    @staticmethod
+    def createWithAvailabilityCheck(client: Client, projectId: str, stageNumber: int, srfResultIndex: int, requiredDataTypes: Optional[set[SolidsDataType]] = None) -> 'SolidResults':
+        '''
+        Check results availability and create a SolidResults instance if available.
+
+        This method first checks if results are available for the specified stage, SRF value, and data types.
+        If results are not available, it raises an exception. Otherwise, it creates and returns a SolidResults instance.
+
+        Parameters:
+            client: Client
+                The gRPC client instance.
+            projectId: str
+                The project ID.
+            stageNumber: int
+                1-based stage index.
+            srfResultIndex: int
+                0-based SRF value index. 0 is to query SRF-None values.
+            requiredDataTypes: Optional[set[SolidsDataType]]
+                A set of SolidsDataType enum values to check availability for. 
+                If None or empty, all data types are queried.
+
+        Returns:
+            SolidResults: A SolidResults instance if results are available.
+
+        Raises:
+            Exception: If results are not available for the specified stage, SRF value, and data types.
+        '''
+        if requiredDataTypes is None or len(requiredDataTypes) == 0:
+            # When no specific data types are required, query all available data types
+            requiredDataTypes = set(SolidsDataType)
+        
+        queryService = SolidsResultsQueryService_pb2_grpc.SolidResultsQueryServiceStub(client.channel)
+        
+        request = SolidsResultsQueryService_pb2.SolidResultsByDataTypesQueryRequest(
+            _projectId=projectId,
+            stageNumber=stageNumber,
+            srfValueNumber=srfResultIndex,
+            requiredDataTypes=[dt.name for dt in requiredDataTypes]
+        )
+        
+        response = queryService.ReadResultsByStageSRFValueAndDataTypes(request)
+        if not response.resultsAvailable:
+            raise Exception(f"Results are not available for stage {stageNumber}, SRF result index {srfResultIndex}, and required data types: {[dt.name for dt in requiredDataTypes]}")
+        
+        return SolidResults(client, projectId, stageNumber, srfResultIndex, requiredDataTypes)
+
+    
+    def getMeshNodeResults(self, entityName: Optional[str] = None, region: Optional[Union[Cube, Cylinder, Sphere]] = None, includeIntersecting: bool = True) -> list[SolidNodalResults]:
+        '''
+        Query solid nodal results at a specific stage and SRF value.
+        Parameters:
+            entityName: Optional[str]: If provided, only nodes belonging to the specified entity are queried.
+            region: Optional[Union[Cube, Cylinder, Sphere]]: Sample region filter. When None, the field is not set in the request (proto3 unset), and the service returns all nodes.
+            includeIntersecting: bool: If True, nodes that intersect the sample region are included. When False, only nodes fully contained are included. Ignored when region is None.
+        Raises:
+            Exception if:
+                - stageNumber is less than 1
+                - stageNumber 
+                is greater than the number of stages in the project
+                - _srfResultIndex is less than 0
+                - _srfResultIndex is greater than the number of SRF values in the project
+        Returns:
+            list[SolidNodalResults]: A list of solid nodal results wrappers for the requested stage and SRF value.
+        '''
+        request = self._makeNodalRequest(entityName, region, includeIntersecting) 
+
+        # Call streaming RPC and process chunks as they arrive
+        stream = self._queryService.QuerySolidNodalResults(request)
+
+        # Extract header from first chunk and accumulate data from subsequent chunks
+        allResults = []
+        totalQueriedNodesCount = None
+        dataTypeToIndexMap: dict[SolidsDataType, int] = {}
+        
+        for chunk in stream:
+            if chunk.HasField('header'):
+                # Process header chunk
+                header = chunk.header
+                totalQueriedNodesCount = header.totalQueriedNodesCount
+                # Convert string keys to SolidsDataType enum
+                for dataTypeName, index in header.dataTypeNameToIndexMap.items():
+                    dataTypeToIndexMap[SolidsDataType[dataTypeName]] = index
+            elif chunk.HasField('data'):
+                # Process data chunk
+                allResults.extend(chunk.data.results)
+
+        if totalQueriedNodesCount != len(allResults):
+            raise RuntimeError(f"Number of nodes received does not match the expected total queried nodes count. Expected {totalQueriedNodesCount}, but received {len(allResults)}.")
+        
+
+        return [
+            SolidNodalResults(r, dataTypeToIndexMap) 
+            for r in allResults
+        ]
+
+
+    def _makeNodalRequest(self, entityName: Optional[str], region: Optional[Union[Cube, Cylinder, Sphere]], includeIntersecting: bool = True) -> SolidsResultsQueryService_pb2.SolidNodalResultsQueryRequest:
+        request = SolidsResultsQueryService_pb2.SolidNodalResultsQueryRequest(
+            baseRequest=self._makeRequest(entityName, region, includeIntersecting),
+            requiredDataTypes=[dt.name for dt in self._requiredDataTypes]
+        )
+        return request
+
+    def _makeRequest(self, entityName: Optional[str], region: Optional[Union[Cube, Cylinder, Sphere]], includeIntersecting: bool = True) -> SolidsResultsQueryService_pb2.SolidResultsQueryRequest:       
+        request = SolidsResultsQueryService_pb2.SolidResultsQueryRequest(
+            _projectId=self._objectId,
+            stageNumber=self._stageNumber,
+            srfValueNumber=self._srfResultIndex)
+        
+        if entityName is not None:
+            entityName = entityName.strip()
+            if entityName:
+                request.entityName = entityName
+        
+        if region is not None:
+            if isinstance(region, (Cube, Cylinder, Sphere)):
+                common_region = region.toCommonGeometryObject()
+                request.sampleRegion.region.CopyFrom(common_region)
+                request.sampleRegion.includeIntersecting = includeIntersecting
+            else:
+                raise TypeError(f"Unsupported region type: {type(region)}")
+
+        return request
+
+
+    def getMeshElementResults(self, entityName: Optional[str] = None, region: Optional[Union[Cube, Cylinder, Sphere]] = None, includeIntersecting: bool = True) -> list[SolidElementResults]:
+        '''
+        Query solid element results at a specific stage and SRF value via streaming.
+        Parameters:
+            entityName: Optional[str]: If provided, only elements belonging to the specified entity are queried.
+            region: Optional[Union[Cube, Cylinder, Sphere]]: Sample region filter. When None, the field is not set in the request (proto3 unset), and the service returns all elements.
+            includeIntersecting: bool: If True, elements that intersect the sample region are included. When False, only elements fully contained are included. Ignored when region is None.
+        Raises:
+            Exception if:
+                - stageNumber is less than 1
+                - stageNumber is greater than the number of stages in the project
+                - _srfResultIndex is less than 0
+                - _srfResultIndex is greater than the number of SRF values in the project
+        Returns:
+            list[SolidElementResults]: A list of solid element results wrappers for the requested stage and SRF value.
+        '''
+        request = self._makeRequest(entityName, region, includeIntersecting)
+
+        # Call streaming RPC and process chunks as they arrive
+        stream = self._queryService.QuerySolidElementResults(request)
+
+        # Extract header from first chunk and accumulate data from subsequent chunks
+        has_user_data = False
+        user_data_map: dict[str, int] = {}
+        all_results = []
+        total_queried_elements_count = None 
+
+        for chunk in stream:
+            if chunk.HasField('header'):
+                # Process header chunk
+                header = chunk.header
+                has_user_data = header.hasUserData
+                total_queried_elements_count = header.totalQueriedElementsCount
+                user_data_map = dict(header.userDataNameToResultIndexMap)
+            elif chunk.HasField('data'):
+                # Process data chunk
+                all_results.extend(chunk.data.results)
+
+        if total_queried_elements_count != len(all_results):
+            raise RuntimeError(f"Number of elements received does not match the expected total queried elements count. Expected {total_queried_elements_count}, but received {len(all_results)}.")
+        
+        return [
+            SolidElementResults(r, has_user_data, user_data_map) 
+            for r in all_results
+        ]

rs3/results/YieldedElement.py

@@ -0,0 +1,33 @@
+import rs3.generatedFiles.GaussPointFailureMessage_pb2 as GaussPointFailureMessage_pb2
+from typing import Type
+
+class GaussPointFailure:
+    def __init__(self, grpcGaussPointFailure: GaussPointFailureMessage_pb2.GaussPointFailure, failureTypeEnum: Type):
+        self._grpcGaussPointFailure = grpcGaussPointFailure
+        self._failureType = failureTypeEnum(grpcGaussPointFailure.failureType)
+
+    @property
+    def XCoordinate(self):
+        return self._grpcGaussPointFailure.location.x
+
+    @property
+    def YCoordinate(self):
+        return self._grpcGaussPointFailure.location.y
+
+    @property
+    def ZCoordinate(self):
+        return self._grpcGaussPointFailure.location.z
+
+    @property
+    def FailureType(self):
+        return self._failureType
+
+
+class YieldedElement:
+    def __init__(self, grpcGaussPointFailure: GaussPointFailureMessage_pb2.GaussPointFailure, failureTypeEnum: Type):
+        self._failurePoint = GaussPointFailure(grpcGaussPointFailure, failureTypeEnum=failureTypeEnum)
+
+    def getFailurePoint(self) -> GaussPointFailure:
+        return self._failurePoint
+
+        

rs3scripting-4.42.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: RS3Scripting
+Version: 4.42.0
+Summary: Client library for interacting with RS3 through python
+Author: Rocscience
+License-Expression: MIT
+Project-URL: Homepage, https://www.rocscience.com/software/rs3
+Project-URL: Documentation, https://www.rocscience.com/help/rs3/overview
+Keywords: Rocscience,RS3,Scripting,RocScript,Geotechnical,Finite Element Analysis,FEM,3D
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: License.txt
+Requires-Dist: grpcio
+Requires-Dist: protobuf<6.0
+Dynamic: license-file
+
+## Introduction 
+This project is a library that can be used to interact with RS3 through python.
+
+Release notes for the library are kept here:
+https://www.rocscience.com/support/rs3/release-notes
+
+RS3 can be downloaded here:
+https://www.rocscience.com/support/program-downloads
+
+The library itself is hosted on PyPi here:
+https://pypi.org/project/RS3Scripting/
+
+### Goal
+Each function exposed corresponds to an equivalent operation you could have done through the UI.  
+Using this idea, the user should be able to edit models and get results without having to go through the UI at all.
+Although only a limited set of functionality is exposed for now, some basic workflows should still be possible. For a list of the functionality we have so far, see [Exposed Functionality](#exposed-functionality).
+
+### Python UI equivalents
+Events and workflows done in the UI will have equivalents in the python library.  
+Wherever a dialog is shown in the UI, there will be an equivalent class with methods that mimick the dialog's behavior.  
+Wherever a warning or error dialog is displayed, an exception will be thrown, or a warning will be displayed in python instead.  
+Wherever you can select and manipulate an entity, identifiers can be used in the library to get references to those entities in python and objects will be constructed to help you interface with them.  
+
+### How it works
+Each function in the library is a wrapper to make an api call to the Application.  
+Objects retrieved through function calls will often not contain any data themselves, but will instead be proxies, allowing you to get information from the objects in the application.  
+For this reason, debugging will sometimes be tricky, as not all data will always be available for you to inspect unless you get it and assign it to a variable yourself.  
+
+### Warnings
+References can be *invalidated* whenever the corresponding object in the application is destroyed or reloaded. You will need to watch out for expired referenecs and renew them when needed as it can cause crashes or incorrect results if not managed properly. Functions that invalidate objects will always be marked with a warning and will indicate which objects should be re-loaded. 
+
+## Exposed Functionality
+The current set of functionality exposed is limited. With this version of the library, you can:  
+- **Model Operations**: Open/save/close models, compute models
+- **Project Settings**: Define stages (names, number), set analysis type (stress, groundwater, dynamic), solver options, units configuration
+- **Selection & Queries**: Select volumes by name, point query, or bounding box (Cube, Cylinder, Sphere regions); filter results by entity
+- **External Volumes**: Assign materials to selected volumes, rename volumes, access volume properties
+- **Material Properties**: Define and modify constitutive models (Mohr-Coulomb, Hoek-Brown, Hardening Soil, Cam-Clay, etc.), hydraulic properties, initial conditions, stage factors, datum dependencies
+- **Support Elements**: Configure liners, bolts, beams, piles, joints, and composite lining systems with full property control and stage factors
+- **Loading Conditions**: Field stress (constant, gravity, advanced options), restraints
+- **Mesh**: Mesh Control
+- **Results Extraction**: Query nodal/element results for solids, liners, bolts, beams, piles, and joints; filter by region or entity name; switch between global and local coordinate systems (e.g., tunnel frames)
+- **Result Types**: Displacements (X, Y, Z, total, normal), stresses, strains, axial forces, moments, shear forces, failure types
+
+## Getting Started
+
+**Getting started guide**  
+https://www.rocscience.com/help/rs3/tutorials/scripting/getting-started-with-rs3-python-scripting 
+
+**Tutorials**  
+https://www.rocscience.com/help/rs3/tutorials/scripting/scripting-tunnel-tutorial-part-1
+https://www.rocscience.com/help/rs3/tutorials/scripting/scripting-tunnel-tutorial-part-2